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Introduction 


This document defines and describes the external structure, appearance, and interfaces of 
Pilot , the operating system for the Mesa processor, and the other packages released with 
it. The description is primarily intended for the designers and implementors of client 
programs of Pilot, i.e., applications, certain development and production tools, test 
programs, etc. It provides sufficient information to allow the programmer to understand 
the facilities available and to write procedure calls in the Mesa language to invoke them 
For each of the facilities of Pilot, this manual lists the procedure names, parameters, 
results, the data types of each of the arguments, and the possible signals which can be 
generated. These are captured in the Mesa definitions modules which are part of each 
release. 

This manual is a reference manual for programmers, who are assumed to be familiar with 
the Mesa programming language. It is not a tutorial on how to write programs which use 
Pilot. The order of information presented, insofar as possible, tries to minimize the 
number of forward references. Cross referencing within the text has been abandoned for a 
more comprehensive referencing via the index. It is expected that the reader will go to the 
index to locate the description of terms or concepts encountered. References in the text of 
the form §1.2.3 refer to section 1.2.3. Deviations from the descriptions given here and the 
currently released version of Pilot are noted in the documentation which accompanies the 
release. 

The specification presented here is adequate for the majority of programs which need to 
interface with Pilot and make use of its facilities. In some cases, however, supplementary 
facilities will be required in order to permit certain applications to make effective use of 
the Mesa hardware and processor. Such facilities, if made generally available, could lead 
to degraded performance or degraded reliability of both Pilot and the whole Mesa system. 
Therefore, they are not described here but are in supplementary documents which are 
made available, along with the corresponding definitions modules, only as required. 

1.1 General structure of system software 

It is important to understand the relationship of the various kinds of software found in a 
Mesa processor. There are the following major categories: 
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Faces , Heads . and Microcode: A face is a Mesa interface that embodies some aspects of 
the processor, defined in the Mesa Processor Principles of Operation , and of its I/O 
devices. Each face is implemented by a combination of Mesa code, called a head, lower 
level machine code, called microcode, and the underlying hardware. The collection of 
heads and microcode provides a machine-independent environment in which Pilot and 
its clients execute. 

Pilot: Pilot is the operating system which manages the hardware resources of, and 
provides the run-time support for, all Mesa programs on a machine. Pilot is written in 
the Mesa language. Its facilities are explicitly invoked by means of procedure calls 
from, or exceptions generated by, client programs. 

Common Software: These are collections of modules and configurations which provide 
services often useful to applications. They are written in Mesa and call upon Pilot 
facilities. Some are released with Pilot while others are released separately. 

Applications: Application software actually performs the functions we are marketing. 
These programs are written in Mesa and may call upon Pilot and Common Software 
for support. 

In addition, there are other categories of software which are important but which will not 
appear in a final product as delivered to a customer. These include the Mesa compiler and 
binder, a number of development tools, test programs, etc. These are designed to operate 
in the environment of Pilot. 

This document deals with Pilot, and the Common Software released with it. However, it is 
not possible to consider Pilot in isolation, and frequent reference must be made to 
documents describing the other categories of software. In particular, the Pilot facilities 
described here would be inadequate for supporting a modern software development project 
in the absence of the Mesa facilities. 


1.2 Files 


The basic facilities of Pilot are incorporated in the object file PilotKernel. bed. There is 
also a special version of Pilot in the object file Utili tyPilotKernel. bed; this version 
is intended to support small applications and utilities which must run in real memory (see 
Appendix D for more details). Some of the facilities described in this manual are 
implemented in their own object files. In those cases, the name of the object file will be 
mentioned in the section that describes the facility. 

There is no explicit mention made in this document of the location of files. That 
information is contained in the documentation that is issued in conjunction with each 
release of Pilot. Readers should consult that documentation to ascertain where files are 
located. 

1.3 General characteristics of Pilot 

Pilot is not a general purpose operating system. Instead, it is a nucleus of software which 
serves as an interface between a Mesa processor and all other software. In particular, 
Pilot defines a "Basic Machine" which is an abstraction of the physical resources provided 
by the hardware. The purpose of this Basic Machine is to define a standard interface 
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which is relatively independent of the size, speed, particular model, and configuration 
upon which it is operating It thus provides a uniform environment in which clients can be 
designed and programmed. Furthermore, it insulates these as much as possible from 
variations in hardware configuration from site to site and from time to time. 

In general, Pilot is designed around the notion that its clients are a cooperative system of 
programs all serving a common purpose. Thus, it is far more tolerant and permissive than 
most operating systems. It delegates much more control of system resources to its users. 
It permits programs and subsystems to recover gracefully from errors, but it also places 
more responsibility on them to ensure the overall well-being of the machine and of the 
networks to which it is connected. 

The major facilities of the Basic Machine can be regarded as falling roughly into three 
main categories: 

Mesa run-time support including processes, monitors, and synchronization facilities 
Virtual memory, files, and volumes 
Stream, device, and communication interfaces 
Each of these categories are described below in some detail. 

Some facilities and concepts normally associated with operating systems have been 
deliberately omitted from Pilot. For example, 

Master Mode and Protection: There is no "ironclad” mechanism which protects Pilot 
from errant or malicious client programs, or even which protects client programs from 
each other. Instead, Pilot consists simply of a group of Mesa modules, and relies on 
such facilities as Mesa type-checking to provide the redundancy necessary to detect 
errors. The protection relationship between Pilot and its clients is the same as that 
between any two systems built in Mesa. 

Job Control: Since product systems have no explicit concept of ”job", Pilot provides no 
job control facilities. Instead, groups of related processes which support a particular 
application control themselves and their use of resources in response to external 
stimuli from the human user, or from other system elements via the Network Services 
(NS) Communication System. 

Billing and Accounting Functions: Since the product architecture is designed around 
the concept of a distributed network of low cost system elements, there is no need to do 
detailed billing or to account for the use of resources within a single system element. 
In those few applications where economic management of resources is required or 
desired, such as in central file servers, this function is performed at a higher level, not 
within Pilot. 

Competitive Allocation of Resources: The allocation of major system resources will 
generally be on a cooperative rather than a competitive basis. Thus, Pilot does not 
contain elaborate resource allocation functions. Instead, resources and resource 
management can often be planned statically when systems are configured. Where 
dynamic resource control is required, such as in the sharing of physical memory, Pilot 
provides facilities which allow the applications to state their current requirements. 
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Complex Services: Pilot does not provide very complex services or facilities such as 
directories, display and keyboard management routines, command languages, or 
human-engineered interfaces. These are all provided by client programs, and are 
likely to vary across the product lines. 

1.3*1 Processes, monitors, and synchronization 

Within a system element, there will almost always be several activities occurring 
concurrently. For example, the display will be updated at the same time as the human 
user is typing on the keyboard, and perhaps both of these will take place at the same time 
files are being read, text is being edited, or documents are being transferred to other 
system elements. To support this kind of concurrent activity, Mesa (with the help of the 
Mesa processor and Pilot) provides the following facilities: 

Processes , which represent asynchronous activities, 

Monitors, which arbitrate access to shared resources, and 

Condition variables , which provide flexible interprocess synchronization. 

These facilities are actually features of the Mesa language, but are described here for 
completeness. 

The concept of process is a fundamental architectural concept in all Mesa software. Mesa 
processes are intentionally "lightweight". They are much more like Mesa procedures 
than, say, entire application programs. A process is instantiated in much the same way 
that a Mesa procedure is called. When this is done, the result is a separate, independently 
executing thread of control, with its own local data (if any). A process has the same status 
as a procedure. A process may call procedures, access local or global data, and spawn new 
instances of processes, subject to the standard Mesa name scoping constraints. A typical 
application may utilize many processes, and the whole processor may contain hundreds of 
process instances at one time. These can be created and deleted frequently (tens, or even 
hundreds of times per second if this proves useful). 

The general philosophy of programming with processes in Mesa is that one or a collection 
of modules manages a particular resource or common data structure. Each process which 
needs to access that resource or data structure calls the procedures defined in those 
modules. To impose order on the possible chaos which could result from asynchronous 
manipulation of the data, the concept of monitor lock is provided. A monitor lock is a data 
structure which contains the interlocks sufficient to guarantee that only one process at a 
time may gain access to the data. It serves as an orderly "meeting ground" through which 
otherwise asynchronous processes may synchronize their activities and ensure the 
consistency of the data or resource which they are sharing. 

In many cases, the exclusive access guarantee of the monitor mechanism is not sufficient 
to express the desired pattern of coordination among cooperating processes. The condition 
variable facility provides additional flexibility in synchronizing such interactions, by 
allowing one process to wait for some event, and another process to notify it when the 
event occurs. Condition variables also provide the basic means in Pilot and Mesa by which 
a process may wait for an event and time out after a specified period of elapsed time if that 
event does not occur. 
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In Pilot, the interfaces to sharable system resources are presented as procedures which 
client programs may call. These procedures almost always define synchronous operations, 
even when they involve the operation of an asynchronously operating device connected to 
the Mesa processor. Thus, some of them may take a long time to complete. In general, if 
an application program cannot tolerate such a long wait, or could make better use of its 
time, it should fork a new process instance to call the Pilot procedure and do the waiting 
for it. Later, when the results are actually required, the two process instances can be 
synchronized and one of them deleted. This is the general mechanism.by which 
asynchronous activity is managed by both Pilot and client programs. The single exception 
to this is in the area of direct control of physical devices, in which Pilot provides a more 
primitive means of implementing overlapped, concurrent activity. Very few clients will 
be directly involved with this interface to Pilot. 


1*3.2 Virtual memory, files, and volumes 

Pilot provides an integrated system for managing main memory and file storage. In 
particular, it implements a single, monolithic, page-oriented, virtual memory shared by 
all Mesa software, including Pilot itself. This virtual memory consists of 2 20 to 232 16-bit 
words, depending upon the hardware processor. The memory is organized into 256-word 
pages. To complement the virtual memory, Pilot provides a system of files, each of which 
may contain up to 2 23 pages (i.e., 232 bytes). Files are aggregated into volumes each of 
which also may contain up to 2 23 pages. Files are accessed via the virtual memory 
swapping mechanism, as described below. 

Traditionally, virtual memories are implemented in operating systems by swapping the 
contents of virtual pages between real memory and some form of backing store. In Pilot, 
the files serve the role of backing store. Any page of virtual memory which contains 
information must have associated with it a page from a file to and from which it can be 
swapped. In the case of pages containing Mesa object code (which are always read-only), 
the backing file is just the object code file output by the Mesa system. In the case of virtual 
memory which "buffers" the contents of files containing long-term data, the files 
themselves act as the backing store. Finally, for pages containing temporary data which 
is purely internal to the current execution of the program, Pilot provides private, 
temporary, anonymous files for backing storage. In UtilityPilot based systems, pages for 
temporary data are only supplied from the processor’s real memory. 

Files are associated with virtual memory by mapping a file or portion of a file to virtual 
memory. The interval of virtual memory used is normally allocated as part of the mapping 
operation. Each map unit , or mapped interval, is typically subdivided into swap units , for 
swapping purposes, as described in the next paragraph. Pilot also provides operations to 
remove the mapping when it is no longer required. 

Whenever a process attempts to reference (i.e., fetch or store) a virtual memory location 
within a map unit, the page containing that location may not be present in real memory. 
If it is not, Pilot must read it into real memory. Execution of the process is suspended until 
the swapping is completed. Pilot provides swapping in two ways: 

under the control of the client program, in the form of swapping commands - these are 
commands by which the client program informs Pilot that certain intervals of virtual 
memory will be needed in the immediate future and that swapping should be initiated 
as soon as possible; An interval is no longer needed and should be swapped out; An 
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interval is not likely to be referenced soon, so Pilot should write it out and release the 
real memory allocated to it. 

on demand — if the page referenced is neither in real memory nor the subject of a 
recent swapping command to bring it in, Pilot will itself initiate a swapping action to 
bring in the that page and any adjoining swapped-out pages of the containing swap 
unit. 

Typically, intervals containing code, and intervals containing local and global frames will 
be swapped on demand, while those which contain the major client data structures and 
data from files will be swapped under client program control. Swapping performance can 
be improved by organizing the Mesa code file(s) so that related procedures are located in 
the same interval of virtual memory, typically by use of the packager. Pilot further 
improves performance by attempting to allocate the pages of a file contiguously on the file 
storage medium so that an interval can be swapped in a single I/O operation. 

A client which wishes to read from a file will map that file into a virtual memory interval 
and then use explicit or demand swapping to cause it to be swapped into real memory. If 
the file is being updated in place, the client will simply store into the relevant locations of 
virtual memory. Subsequently, when the interval is unmapped or otherwise swapped out 
of real memory, the file will reflect the new contents. If, on the other hand, the file is not 
being updated in place, the client program can copy the contents of a virtual memory 
interval to a portion of a file, and copy a portion of a file to a virtual memory interval, 
without altering the mapping of the interval. 

Pilot supports access to files on local volumes. Each existing file is uniquely defined 
within that volume. If that volume is implemented on a removable medium, it (and all of 
its files) may be removed and remounted on another system element. 

Files are identified by file ids. When a new file is created, a new file id is issued. The file is 
uniquely identified to Pilot by presenting Pilot with its id and the id of the containing 
volume. Client may not generate file ids , but they may store them, copy them, and pass 
them to other programs. 

An important interval of virtual memory recognized by the Mesa processor and the Mesa 
system is the main data space (MDS). This is a contiguous subset of virtual memory 
consisting of 2 16 words (256 pages), any part of which may be addressed by a sixteen-bit 
Mesa pointer. An MDS contains the low-level data structures and mechanisms, such as 
local and global frames and trap handlers, necessary for executing Mesa processes. 
Conversely, each process is associated with one and only one MDS. Although the Mesa 
processor supports multiple coexisting MDS’s, Pilot does not. Thus, any Pilot-based 
system has only one MDS, which is shared by all of the system’s processes. 

L3.3 Stream, device, and communication interfaces 

Pilot supports a sophisticated, packet-switched, communication system. The heart of this 
system is a software package called the router. 

Information received from one Pilot client for transmission to another Pilot client (on the 
same or another system element) is broken into packets for delivery. These packets, 
encapsulated in the Xerox Internet Transport Protocols and including both source and 
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destination addresses, are passed to the router. If the destination client is on the local 
machine, the packet is passed to that client. 

For remote destination clients, the router determines if there is a communication path 
from the local machine to the final destination machine. If no path exists, the packet 
cannot be transmitted, and an appropiate status is set. Otherwise the best available path 
is selected and the packet is transmitted via the first communication link of the path on 
route to its final destination. This physical transmission may take place on any one of a 
number of communication devices, including the ethernet or telephone lines. 

The router sends and receives packets via ethernet device drivers and by other 
communication device drivers which may be added in the future. On the Pilot client side, 
the router is accessed by the NetworkStream and PacketExchange interfaces (see Chapter 6). 

Pilot establishes a style and some standards for the construction of I/O device drivers by 
defining the notion of channel . This makes the style of usage of the various I/O drivers 
similar enough to be somewhat predictable and standard enough that a client constructed 
I/O device driver can be included in Pilot without a formal integration. All of the Pilot- 
supplied and Pilot-required device drivers conform to this style and these standards. 

One such Pilot-supplied device driver is the ethernet device driver. The ethernet device 
driver not only may be used to transmit Internet Transport Protocol packets through the 
router as described above, but may also be used as an ordinary device driver for non-NS 
communication with non-NS stations. 

When sequential data is to be transported between a Pilot client and an I/O device or 
another Pilot client, it is usually possible to do this in a device and format independent 
way. The Pilot Stream Package accomplishes this. The mechanism for transcribing a 
sequential stream of data on or off an I/O device is provided by a client written or Pilot- 
supplied transducer. Modifications to the data stream (e.g., code conversion) are 
accomplished by a client or Pilot filter. The stream package provides a basic set of 
transducers and filters and, more important, a way of assembling them sequentially into 
processing and transmitting pipelines. 

One kind of stream supported directly by Pilot is the Network stream referred to above. 
This kind of stream is capable of receiving data from a Pilot client on one machine and 
transmitting it to another client on a different machine. 

1.4 Pilot concepts 

There are methodologies which are used repeatedly in the design of the Pilot functions. 
They are described here. 

1.4.1 Stateless enumerators 

Many Pilot functions return information to the client of the form of a list of items whose 
length cannot be a priori known. Consequently, Pilot functions that supply this type of 
information do so by passing back an item of the list for each call for the information. 
These functions are created in a very stylized way. 

The basic idea is that the client, on its first call to such a function, supplies a value which 
no item of the list can have. This item is usually has a name of the form null object, for 
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whatever object is being enumerated. The function returns a member of the list. If the 
client, on its next call on the list function, supplies the previously returned value, Pilot 
will return another member of the list. This goes on until the list is exhausted where upon 
Pilot returns nuWobject, indicating the end of the list. 

These types of functions are called stateless enumerators. A reference to a stateless 
enumerator will always be accompanied by the beginning and ending values. Usually the 
items of the list are not returned in any particular order. If there is some order imposed, 
this will be pointed out in the description of the function. 

1.4.2 Synchronous and asynchronous operations 

When a Pilot function is called, it may or may not return before the requested operation 
has been completed. If Pilot waits until the operation is done (the usual case), the 
operation is called synchronous. If the operation queues the operation and returns before 
it has completed, it is dubbed asynchronous . If no mention is made of the type of a 
particular operation, the operation is synchronous. Almost all Pilot operations are 
synchronous. 

1.5 Notation and conventions 

At the beginning of each section are listed the names of the definitions modules containing 
the Pilot facilities described in that section. The procedure and type definitions contained 
in each of the interface modules are presented in this document as pseudo-Mesa 
declarations of the form: 

ModuieName.TypeName: type * ... ; 

ModuieName.ProcedureName: procedure [ParameterList] returns [ResultsList]; 

ModuieName.SignalName: signal [ParameterList] returns [ResultsList]; 

That is, each definition is listed with its own name qualified by the definitions module 
name. Any Mesa program which invokes the facilities of Pilot must list the names of the 
relevant definitions modules in its directory clause. It may then refer to one of these 
variables, procedures, types, or signals by its fully, qualified name. This style of explicit 
qualification is strongly recommended (i.e., as opposed to opening the scope of the 
definitions module by an open clause, and using the unqualified name). 

Accompanying these Mesa declarations is the explanation of the function of each 
procedure, the conditions under which it may be invoked, and the signals and ERRORS it can 
raise. In this explanatory text, the explicit interface qualification is usually dropped, 
since it is clear from the context. 

The following rules apply to all the operations discussed in this manual. Exceptions to the 
rules will be mentioned explicitly. 

1) If the explanatory text of an operation does not explicitly say that a specific error 
is raised, then the operation does not raise the error. 
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2) If an operation returns by raising an error, then the operation will appear to have 
only raised the error 

3) If an operation is to operate on a object already operated on ( e.g ., 
Space.MakeReadOnly on a read-only object), then the operation will return 
successfully. That is, most operations are idempotent. 

4) All operations that may be performed outside the body of a catch phrase, may be 
performed within the body of the catch phrase (e.g.. Pilot holds no monitor locks 
while raising a signal or error). 

5) Invoking an operation with a count parameter of zero, is equivalent to invoking 
the operation with a count of one minus one (i.e., zero is not a special case). 

Note: A paragraph in this form headed by the word "Note" contains additional 
information about how the operations are intended to be used. These are included to help 
the programmer to design his program to take best advantage of the Pilot facilities. 
Ignoring these notes will not produce incorrect programs, but it may produce programs 
that execute slowly, or require excessive amounts of system resources. 

Caution: Paragraphs labeled with "Caution" are intended as warnings to programmers. 
In general, these apply to features or aspects of Pilot which can be easily misused, and 
which will result in incorrect or inconsistent operation if they are misused. In particular , 
Pilot is not likely to be able to detect errors cautioned against in these paragraphs . It is the 
programmer's responsibility to avoid making these mistakes. 

For example, an error which Pilot cannot detect is the "dangling reference" problem. In 
many cases, Pilot defines a class of abstract objects and provides client programs handles 
for accessing such objects. If one client program should request Pilot to destroy a 
particular object, then later another client program requests Pilot to create a new one of 
the same type, Pilot may reuse the handle of the old, destroyed one. If the first client 
program inadvertently retains and uses copies of the old handle, these will now look like 
legitimate handles for the new object. Pilot may not be able to detect the condition and 
chaos is likely to ensue. 

Metasymbols are indicated with italics. It is expected that some specific instance will be 
filled in for the metasymbol, such as in the case of nuWobject in the preceding section. A 
possible instance of a nuWobject might be nullHandle. 

1.6 Common Software 

This manual also includes descriptions of the Common Software. Common Software is 
not included in PilotKernel.bcd, but is made available as separate object files. Clients 
which make no use of Common Software need not be burdened with its presence. Common 
Software comes in two varieties, Product and Development. Those Common Software 
packages denoted as Product Common Software are intended to be used in products. 
Development Common Software consists of packages that are used internally, in the 
development environment; they should not be used in product systems. Only Product 
Common Software is described in this manual. 
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Because the Common Software packages are not included in PilotKernel.bcd, the name of 
w the implementing object file, how to bind, etc. is presented at the beginning of each section 
describing a Common Software package. 

L7 What follows 

The rest of the manual describes the interfaces to Pilot and the Common Software 
packages in terms of the Mesa data types and procedures used by clients. These types and 
procedures are embodied in one or more Mesa interfaces (definitions modules) made 
available to programmers of client software. The description is organized according to the 
major resources managed by Pilot. 

Chapter 2 describes the interface provided by Pilot to various Mesa processor features. 
Described are the various constants and types associated with the processor. It also 
describes the run-time support needed to execute Mesa programs. This chapter includes 
the descriptions of facilities to support the Mesa concepts of process , monitor , and 
condition variable and the various traps, procedures, and signals defined by the Mesa 
language. It describes some basic, low-level system facilities provided by Pilot. These 
include: universal identifiers , by which volumes and other objects are named; network 
addresses , which control communication via the Xerox Internet Transport Protocols; 
several forms of timekeeping facilities; and facilities for controlling system electrical 
power. 

* 

In Chapter 3, the general concept of a stream is introduced. Streams may be superimposed 
upon files, communication facilities, and devices in order to achieve a high level, medium 
independent means of accessing and distributing information. 

Chapter 4 describes the file management and virtual memory facilities of Pilot. 

Chapter 5 describes the facilities by which client software can exercise control over 
hardware devices. These facilities are meant primarily for situations in which streams 
are not suitable. This chapter is a model for individual device interfaces, some of which 
are described in this manual, and others of which are implemented by clients. 

Chapter 6 describes the communication facilities of Pilot. 

Chapter 7 describes miscellaneous editing and formatting packages. 

Chapter 8 describes how to initialize the system, and how to get a client to start execution. 

Chapter 9 describes facilities for automatically handling system errors and signals. The 
processing of error conditions is done by a separate program referred to generically as a 
backstop. 




Environment 


This chapter describes the constants, types, and procedures, available to the Pilot 
programmer, which describe the system element and make available at the client level, 
certain features of the abstract machine. It contains the basic levels of the system. 

2.1 Processor environment 

Environment: definitions 

This section captures all of the basic constants describing the processor and peripherals. 
The first section describes the processor and the second defines the constants pertinent to 
the peripheral devices attached to the processor. 

2.1.1 Basic types and constants 

Pilot is specifically designed to execute on system elements defined by the Mesa Processor 
Principles of Operation. For convenience, the basic types and constants of that 
architecture are captured symbolically in the definitions module Environment. 

The following definitions define the basic word, byte and character sizes of the Mesa 
processor. 

Environment.Byte: TYPE a [0..255]; 

Environment. Word: type * [0..65535]; 

Environment. bitsPerWord: CARDINAL a 16; 

Environment.bitsPerByte, Environment.bitsPerCharacter: CARDINAL a 8; 
Environment.logBitsPerWord: CARDINAL = 4; 

Environment.bytesPerWord, Environment. charsPerWord: CARDINAL a 
bitsPerWord / bitsPerCharacter; 

Environment.logBitsPerByte, Environment.logBitsPerChar: CARDINAL = 3; 
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"Environment.logBytesPerWord, Environment. logCharsPerWord: CARDINAL = 1; 

All constants of the form log... are base 2 logarithms of their respective quantities. The 
following type is a general purpose descriptor for a sequence of bytes in virtual memory 
(see section §4.5 for a description of virtual memory). 

Environment.Block: TYPE as RECORD[ 

blockPointer: LONG POINTER TO PACKED ARRAY [0..0) OF Environment.Byte, 
startlndex, stopIndexPlusOne: cardinal]; 

The following constant defines an empty block. 

Environment.nullBlock: EnvironmentBlock = [NIL,0 # 0]; 

The following definitions characterize the basic page size of the Mesa processor. 

Environment. wordsPerPage: CARDINAL = 256; 

Environment.bytesPerPage, Environment.charsPerPage: cardinal = wordsPerPage * 
bytesPerWord; 

Environment.log WordsPerPage: cardinal - 8; 

Environment.logBytesPerPage, Environment.logCharsPerPage: cardinal « 
logWordsPerPage + logBytesPerWord; 

The following definitions characterize the maximum virtual memory address space 
available to Pilot clients. 

Environment.maxPagesInVM: CARDINAL S EnvironmentJastPageCount; 

This is one less than the number of VM pages provided by the hardware. The highest 
numbered VM page is reserved for system purposes. 

Environment.maxPagesInMDS: cardinal = 256; 

Environment. PageNumber: TYPE ■ long cardinal; ~[0..2 24 -1)~ 

Environment.fi rstPageNumber: Environment. PageNumber a 0; 

Environment.lastPageNumber: Environment.PageNumber a 16777214; ~2 24 -2«- 

Note: Because LONG subrange types are not implemented in the current version of Mesa, 
the current version of Pilot defines PageNumber as a long cardinal and defines the 
constants firstPageNumber and lastPageNumber to specify FiRST[PageNumber] and 
LA$T[PageNumberj. Similarly for PageCount and PageOffset below. 

Environment. PageCount: TYPE = LONG CARDINAL —[0-.2 24 -1 ]--; 

Environment.fi rstPageCount: Environment. PageCount = 0; 

EnvironmentJastPageCount: Environment. PageCount = lastPageNumber + 1; « 2 24 -1 
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Environment. PageOffset: TYPE * Environment. PageNumber; 

Environment.fi rstPageOffset: Environment.PageOffset 3 0; 

Environment. lastPageOffset: Environment.PageOffset * lastPageNumber; 

Caution: Substituting LASTfEnvironment. PageNumber] or LASTfEnvironment.PageCount] for 
the above constants will yield incorrect results. 

Environment.Base: TYPE a LONG BASE POINTER; 

Environment.firSt€4K: Environment. Base a ...; 

first64K is the base pointer to the first 64K of virtual memory. 

Environment.maxiNTEGER: INTEGER a LASTflNTEGER]; 

Environment.miniNTEGER: INTEGER a FIRST[INTEGERl; 

Environment.maxCARDINAL: INTEGER a LAST[CARDINAL]; 

Environment.maXLONGINTEGER: INTEGER a LAST[LONG INTEGER] ; 

Environment.minLONGINTEGER: INTEGER a FIRST[LONG INTEGER]; 

Environment.maXLONGCAROINAL: INTEGER a LAST[LONG CARDINAL]; 

The following types allow direct manipulation of long values. 

Environment.Long, Environment. LongNumber: TYPE = MACHINE DEPENDENT 
RECORD [SELECT OVERLAID * FROM 
1C a > [lc: LONG CARDINAL], 
li a > [|i; LONG INTEGER], 

Ip a > [|p; LONG POINTER], 

lu a > [lu: LONG UNSPECIFIED], 

num a > [lowbits, highbits: cardinal], 

any a > [low, high: unspecified], 

endcase]; 

The following structure is used to address bits (used principally by BitBlt). 

Environment.Bit Address: TYPE a MACHINE DEPENDENT RECORD [ 

word: long pointer, 

reserved: [O..LAST[woRD]/Environment.bitsPerWord) <-0, 
bit: [O..Environment.bitsPerWord)]; 

Note that the reserved field must be zero. 

The following operation returns a LONG pointer to the first word of a page. 

Environment-LongPointerFrornPage: procedure [page: Environment.PageNumber] 

RETURNS [LONG POINTER]; 
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The following operation returns the number of the page containing pointer. If pointer is 
NIL, the value returned is undefined-no signal is raised. 

Environment.PageFromLongPointer: procedure [pointer: long pointer] 

RETURNS [Environment.PageNumber]; 

2.1.2 Device numbers and device types 
Device: definitions 
D eviceTypes: definitions 

Definitions are provided for devices and classes of devices attached to the system element. 
These constants are defined in the interfaces Device and DeviceTypes. Definitions in the 
interface Device serve to identify the individual devices attached to the system element. 

Device.Type: type = record [cardinal]; 

Device.nullType: Device.Type a [0]; 

Device.Ethernet: type = cardinal [5..16); 

* Device.PilotDisk: type a cardinal [64..1024); 

All Ethernet type devices will have a value in the range defined by Ethernet. All devices 
capable of containing a Pilot physical volume will be in the range defined by PilotDisk. 

Device types provide a means of classifying the different devices attachable to the system 
element. Device types for Ethernet devices are: 

DeviceTypes.anyEthernet: Device.Type a ...; 

DeviceTypes.ethemet: Device.Type = ...; 

DeviceTypes.ethernetOne: Device.Type = ...; 

A type of anyEthernet indicates that the device is an Ethernet but of unspecified type. A 
type of ethernet indicates that the device is a 10 megabit Ethernet. A type of ethernetOne 
indicates that the device is a 3 megabit Ethernet. 

The specific device types assigned to Pilot disks are: 

DeviceTypes.anyPilotDisk: Device.Type = ...; 

DeviceTypes.salOOO: Device.Type a .. . ; 

DeviceTypes.sa1004: Device.Type = . . . ; 

DeviceTypes.sa4000: Device.Type a . .. ; 

DeviceTypes.sa4008: Device.Type a ... ; 
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DeviceTypes.t300: Device.Type = . . . ; 

DeviceType$.t80: Device.Type = . . . ; 

DeviceTypes.cdc9730: Device.Type = ...; 

DeviceTypes.q2000: Device.Type » ...; 

DeviceTypes.q2010: Device.Type a .. . ; 

DeviceType$.q2020: Device.Type = ...; 

DeviceTypes.q2030: Device.Type = ...; 

DeviceTypes.q2040: Device.Type = .. . ; 

DeviceTypes.q2080: Device.Type * . . . 

A type of anyPilotDisk indicates that the device is a Pilot disk but of unspecified type. 

A type of sal000 indicates that the device is some unspecified disk of the Shugart 
Associates SA1000 family. Similarly, a type of sa4000 indicates that the device is some 
unspecified disk of the Shugart Associates SA4000 family. A type of sal 004 indicates that 
the device is an SA1004 disk, a type of sa4008, an SA4008 disk. 

A type of t300 indicates that the device is a Century Data Systems T-300 disk. A type of 
t80 indicates that the device is a Century Data Systems T-80 disk. A type of cdc9730 
indicates that the device is a Control Data Corporation CDC-9730 disk. 

A type of q2000 indicates that the device is some unspecified disk of the Quantum 2000 
family. Types of q2010, q2020, q2030, q2040, and q2080 indicate Quantum disk devices of 
type 2010, 2020, 2030, 2040, and 2080, respectively. 

Other device types included in the interface are: 

DeviceTypes.null: Device.Type = Device.nullType; 

DeviceTypes.sa800: Device.Type a . . . ; 

A type of sa800 indicates that the device is some unspecified disk of the Shugart 
Associates sa800 family. 

When indicating devices capable of holding a Pilot volume, Pilot will report a correct 
device type, although it may not be as specific as possible (i.e., a Shugart SA4008 disk 
might be reported as either DeviceTypes.anyPilotDisk or DeviceTypes.sa4000 or 
DeviceTypes.sa4008. 

The following Extras interfaces are interim for this release. In future releases, all Extras 
interfaces will be merged with their parent interfaces. 

DeviceTypesExtras.anyFloppy: Device.Type =_; 
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DeviceType$Extras.sa850: Device. Type = . . . ; 

DeviceTypesExtras.sa455: Device. Type = ... ; 

DeviceTypesExtras.sa456: Device. Type = ... ; 

DeviceTypesExtraExtras.m2235: Device. Type a .. . ; 

DeviceTypesExtraExtras.m2242: Device. Type = . . . ; 

DeviceTypesExtraExtras.m2243: Device. Type = . . . ; 

A type of anyFloppy indicates that the device is a floppy drive but of unspecified type. 

A type of sa850 indicates that the device is a Shugart Associates SA-850 floppy drive. 
Similarly, a type of sa455 or sa 456 indicates that the device is a Shugart SA-455 or SA- 
456 floppy drive, respectively. 

A type of m2235 indicates that the device is a Fujitsu 26MB rigid disk drive. Similarly, a 
type of m2242 or m2243 indicates that the device is a Fujitsu 50MB or 80 MB rigid disk 
drive, respectively. 


2.2 Processor interface 

This section presents interfaces, provided by Pilot, that permit access to features provided 
by the underlying Mesa processor which are not provided by the Mesa language. These 
interfaces define pseudo-faces-types defined by the hardware and operations directly 
implemented by the hardware. Pilot merely exports the definitions for the use of its 
clients. The types and operations are defined below. 

2.2.1 BitBlt 

BitBlt: DEFINITIONS...; 

The Bit Block Transfer operation in this interface is bitblt which operates on rectangular 
arrays of bits in memory. The instruction accesses source bits and destination bits, 
performs a function on them, and stores the result in the destination bits. 

Successive bit pairs are obtained by scanning a source bit stream and a destination bit 
stream. The instruction operates successively on lines of bits called items ; it processes 
width bits from a pair of lines, and then moves down to the next item by adding srcBpI (bits 
per line) to the source address and dstBpI to the destination address. It continues until it 
has processed height lines. 

Figure 2.1 illustrates a possible configuration of source and destination rectangles, which 
are always of the same size and dimensions, embedded in separate bitmaps. 
Approximately half of the items have been moved to the destination, and the location of 
the next item is highlighted in the source bitmap and shown as a dotted line in the 
destination bitmap. 

BitBlt.BiTBLT: procedure [ptr: BBptr] 
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dstBpI 



srcBpI 


Figure 2. 1 BitBlt Source and Destination 


The argument to Bit Block Transfer is a short pointer to a record containing the source 
and destination bit addresses and bits per line, the width and height (in bits) of the 
rectangle to be operated on, and a word of flags that indicate the operation to be 
performed. The width and height of the rectangle are restricted to a maximum of 32,767. 
The argument record must be aligned on a sixteen word boundary. 

BitBlt-AlignedBBTable: procedure [ip: pointer to BBTableSpace] returns [b: BBptr] ; 

BitBlt. BBTableSpace: type ■ array [1..siZE[BBTable] + BBTableAlignment) of unspecified; 

BitBit.BBTableAlignment: cardinal * 16; 

AlignedBBTable ensures that the BBTable will be on a sixteen word boundary. 

BitBIt.BBptr, BitBlt.BitBltTablePtr: type * pointer to BBTable; 

BitBit.BBTable, BitBit.BitBltTable: type = machine dependent record [ 
dst: BitAddress, 
dstBpI: INTEGER, 
src: BitAddress, 
srcDesc: SrcDesc, 
width: CARDINAL, 

height: cardinal, 
flags: BitBltFlags, 
reserved: unspecified «-0j; 

This table contains all the arguments for specifying the resultant bit pattern. The 
following types are used to make up a BitBltTable (BBTable). 

BitBit.BitAddress: type a Environment.BitAddress; 

BitAddress is used to address bits. 
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BitBit.SrcDesc: type = machine dependent record [ 

SELECT OVERLAID * FROM 
gray * > [gray: GrayParm], 
srcBpI « > [srcBpI: integer], 
endcase]; 

The description of the source may be a pattern to be repeated or may be particular bits. In 
the case of a pattern, the gray field would be selected. This is described in detail under 
Gray Flag following. 

BitBlt.BitBltFlags: TYPE a MACHINE dependent record[ 
direction: Direction forward, 
disjoint: boolean false, 
disjointltems: boolean false, 
gray: boolean false, 
srcFunc: SrcFunc null, 
dstFunc: DstFunc null, 
reserved: [0 511 0]; 

Direction Flag 

The direction flag indicates whether the operation should take place forward (left to right, 
from low to high memory addresses) or backward (right to left, from high to low memory 
addresses). This allows an unambiguous specification of overlapping BitBits, as in 
scrolling. 

BitBit.Direction: type * {forward, backward}; 

If the direction is backward, the source and destination addresses point to the beginning of 
the last item of the blocks to be processed, and the source and destination bits per line 
must be negative . This restricts the width of the bitmaps involved to a maximum of 32,767 
bits. 

Disjoint Flag 

If the operation's source and destination are completely disjoint, the implementation 
performs the operation from left to right, top to bottom. 

Both the direction and the disjointltems flags in the argument record are ignored in the 
case that disjoint is set. 

Disjointltems Flag 

If the individual items of the source and destination are disjoint, but the rectangles 
otherwise overlap, the disjointltems flag should be set (and the disjoint flag should be 
clear); this allows the implementation to perform the operation so that, within each item, 
the bits are processed in the most efficient horizontal direction. The items are processed in 
the order indicated by direction. 

If neither disjoint nor disjointltems is set, the implementation processes the items and the 
bits within items in the direction indicated by the direction flag. 
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Gray Flag 

The gray flag allows repetitive bit patterns to be specified in a condensed format. The 
usual application is for generation of various shades of gray on the display, but any 
repetitive pattern within the limits stated below may be supplied. 

If the gray option is specified, the srcBpI field of the argument record is reinterpreted as 
follows: Note also that the gray case is always forward and completely disjoint 
(disjointltems is ignored). 

BitBit.GrayParm: type * machine dependent record [ 
reserved: [0..15] <-0, 
yOffset: [0..15], 
widthMinusOne: [0..15], 
heightMinusOne: [0..15]]; 

The fields grayparm.widthMinusOne and grayParm.heightMinusOne define the width 
(less one) in words and height (less one) in bits, respectively, of a gray brick located at 
arg.src. (see figure 2.2). Note, the term "brick” refers to a rectangular area containing the 
gray pattern to be copied. Conceptually, this brick is replicated horizontally and vertically 
to tile a plane of dimensions arg.width and arg.height that becomes the source rectangle 
of the operation. This brick is a maximum of sixteen words wide and sixteen lines high. 
Patterns, therefore, are also limited to a repetition rate of sixteen in each direction. To 
guarantee correct repeatability of the pattern in the horizontal direction, it is usually the 
case that the width of the gray brick (in bits) is a multiple of the repetition rate; the height 
of the gray brick is usually equal to the vertical repetition rate. 

Proper alignment of the gray pattern with the destination bitmap requires the initial x 
and y offsets into the brick in addition to its width and height. The initial x offset is 
derived from arg.src as follows: arg.src.word always points to the beginning of the first 
line to be transferred (not to the origin of the gray brick). The x offset of the first bit to be 
transferred is supplied by arg.sre.bit; this bit is always in the first word of the line. The 
initial y offset is the number of lines down from the origin of the brick and is specified by 
grayParm.yOffset; subtracting the y offset times the brick width from arg.src.word gives 
the origin of the gray brick. 

Source and Destination Functions 

BitBit.SrcFunc: type = {null, complement}; 

BitBlt.DstFunc: type = {null, and, or, xor}; 

The functions available for combining the source and destination rectangles are shown in 
Figure 2.3. 

The src field has two options; the null selection indicates using the source rectangle as is 
for the destination function. The complement selection will invert the source bits in the 
destination function. 

The dst field determines the function to be used for changing bits in the destination 
rectangle. The null selection causes the destination to be "replaced” with the source bits. 
There is no boolean operation in this case. Anding the destination bits with the source bits 
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leaves only those bits in common in the destination. "Painting” the destination requires 
oring. This will leave the union of the two sets of bits in the destination. The last function 
is the xor. This essentially masks out the matching bits leaving the union but not the 
intersection of the bits in the destination rectangle. 

2.2.2 TextBlt 

TextBlt:DEFINITIONS ...; 

The Text Block Transfer interface operates on an array of characters; it implements three 
functions useful in generating the font representation of the text in a bitmap. It may 
calculate the number of characters on a line, convert characters to their font 
representation, or widen or narrow select characters for justification. There is more 
discussion on these functions later in this section. 

TextBIt.TextBlt: PROCEDURE [ 

index: cardinal, bitPos: cardinal, micaPos: cardinal, count: integer, 
ptr: pointer to TextBItArg] 
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RETURNS [ 

newlndex: cardinal, newBitPos: cardinal, newMicaPos: cardinal, 
newCount: integer, result: Result]; 

TextBlt proceeds through the text until either there is no more text or a stop character is 
encountered; it maintains the bitPos and the micaPos of the origin of each character, and 
increments the count of the number of pad characters processed. The new character 
positions are returned along with the result of what caused the completion. 

TextBitTextBItArgAlignment: cardinal » 16; 

TextBlt.TextBItArgSpace: type ■ array [1..siZE[TextBltArg] + TextBItArgAlignment) of 
unspecified; 

TextBlt AlignedTextBItArg: procedure [ip: pointer to TextBItArgSpace] 

RETURNS [p: POINTER to TextBItArg] 

TextEdit's static arguments are passed via a short pointer to a record; the argument record 
must be aligned on a sixteen word boundary. 

TextBltTextBltArg: type = machine dependent record [ 
reserved: [0..37777B] <—0, 
function: Function, - display, format or resolve 
last: cardinal, ~ index of last character to process 
text: long pointer to packed array cardinal of character, 
font: FontHandle, - Long Pointer to font information 
dst: long pointer, ~ destination bitmap (display only) 
dstBpI: cardinal, - Bits per line (display only) 
margin: cardinal, - mica value of right margin (format only) 
space: integer, - width adjustment to pad characters (display, resolve) 
coord: long pointer to array cardinal [0..0) of cardinal -- widths array for resolve 
]; 


The limits of the text that TextBlt operates on are arg.text to arg.last. Depending on the 
function specified (explained below) specific args will be pertinant. During the format 
function, the scan is terminated before the right arg.margin (in micas) is passed. The 
display function Ors the character's font bits into the destination bitmap specified by 
arg.dst and arg.dstBpI (bits per line). The resolve function saves the bitPos of the origin of 
each character in the array arg.coord. 

Justification can be accomplished using the display and resolve functions with 
appropriate settings of the arg.space and count values; arg.space is added to the width of 
every pad character (it may be negative), and count is incremented each time a pad 
character is encountered (it may also be initially negative). Since the amount of white 
space to be absorbed by (or squeezed out of) pad characters is rarely an even multiple of the 
number of pad characters, pad characters encountered have arg.space + 1 added to their 
widths as long as count is negative. Thus if sixteen bits need to be added to the width of 
the line in order to justify it, but it contains only thirteen pad characters, arg.space would 
be set to one, and count would be initialized to negative three; this will result in widening 
the first three pad characters by two bits, and the remaining ten pad characters by one bit 
each. 
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TextBlt.Function: type = {display, format, resolve}; 

The TextBlockTransfer implements three functions useful in generating the font 
representation of the text in a bitmap. The format function is used to calculate the number 
of characters that will fit on a line, given its right margin (in micas). The display function 
converts characters to their font representation in the destination bitmap, optionally 
widening or narrowing pad characters to perform line justification. The resolve function is 
used to record the horizontal bit position of the origin of each character in the bitmap; it 
also handles justification. 

Caution: Because of kerning, the display function may place bits into the destination 
bitmap to the left of the bitPos of the leftmost character and to the right of the right 
margin. It is the programmer’s responsibility to initialize the bitPos to allow for the left 
kerning of the first character, and to supply a bitmap wide enough to allow for the 
maximum possible right kerning. Kerning is further explained below. 

TextBlt.FontHandle: type a long pointer to Font; 

TextBit.Font: type; 

TextBlt.FontHandle points to the font information TextBlt needs. The interface Fonts 
describes the TextBlt font type. TextBltFontFormat.FontRecord is the concrete type of a 
TextBit.Font. TextBltFontFormat.FontRecord must be aligned on a sixteen-word boundary. 

TextBitFontFormat.fontRecordAlignment: natural a 16; 

TextBltFontFormat.FontRecord: TYPE a MACHINE DEPENDENT RECORD [ 
fontbits(O): FontBitsPtr, 
fontwidths(2): FontWidthsPtr, 
fontchar(4): FontCharPtr, 
rgflags(6): RgFlagsPtr, 
height(8): cardinal]; 

The following types make up FontRecord: 

TextBItFontFormat: FontBitsPtr: TYPE a LONG BASE POINTER TO ARRAY [0..0) OF UNSPECIFIED; 

The data at TextBItFontFormat.FontBitsPtr is a base pointer for the character raster data. For 
a particular character, TextBItFontFormat.CharEntry.offset (defined below) is added to this 
base to get the address of the character’s raster.The raster format includes the scan lines 
within the dimensions given by fontwidths and fontchar. The height of the raster is 
constant for all characters. 

The memory order of the bits in the raster correspond to the memory order that TextBlt 
will paint them into the destination bitmap. Said another way, TextBlt paints the first 
scan line of the raster into the appropriate place in the first scan line of the destination 
bitmap, and so on. Similarly, the first bit of a raster’s scan line is painted into the 
appropriate first bit of the scan line in the destination bitmap, and so on. 

In conventional Xerox bitmap displays, the first scan line in memory corresponds to the 
top line on the screen, and the first bit of a scan line corresponds to the left pixel of the line. 
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For this case, the first scan line in the raster will be the topmost row of the character, and 
the first pixel (most significant bit) of a scan line will be the leftmost pixel of its row. 

TextBltFontFormat.FontWidthsPtr: type = long pointer to FontWidths; 

TextBItFontFormat. FontWidth S: TYPE a PACKED ARRAY CHARACTER OF PixelWidth; 

TextBItFontFormat.PixelWidth: TYPE a CARDINAL [0..377B]; 

The width of the font is dependent on the width of the pixel. 

TextBItFontFormat. FontCharPtr: type a long pointer TO FontChar; 

TextBItFontFormat.FontChar: TYPE a array character of CharEntry; 

CharEntry must be aligned on a two-word boundary. 

TextBItFontFormat.charEntryAlignment: NATURAL a 2; 

TextBItFontFormat.CharEntry: TYPE a machine dependent record [ 
leftKern(0:0..0): boolean, 
rightKern(0:1..1): boolean, 
offset(0:2..15): RasterOffset, 
mica(1): cardinal]; 

If CharEntry.leftKern = true, the character's raster has one column preceeding the char's 
origin, and is to be written into the destination bitmap one column preceeding the current 
position (bitPos). If CharEntry.rightKern = true, the raster extends one column past the 
spacing width into the space for the next char; that char's raster should begin coincident 
with the current char's last column (one column preceeding where it would normally go). 

CharEntry.offset is the offset for the address of the character’s raster. 

TextBItFontFormat. RasterOffset : type = cardinal [0..37777B]; 

Mica indicates the "physical” width of the char (typically in micas). 
TextBltFontFormat.RgFlagsPtr, RgflagsPtr: type a long pointer to RgFlags; 
TextBItFontFormat.RgFIags; type = packed array character of Flags; 

TextBItFontFormat.Flags: TYPE a MACHINE DEPENDENT RECORD [ 

pad(0:0..0): boolean, 
stop(0:1..1): boolean]; 

The pad flag allows the character to have its width increased or decreased (in bits) for line 
justification. The stop flag will specify a stop character to terminate a TextBlt operation. 

TextBltFontFormat.maxLeftKern: CARDINAL a 1; 

TextBItFontFormat.maxRightKern: cardinal a 1; 
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MaxLeftKern and maxRightKern support kerning up to one pixel in the respective 
direction. 

TextBlt.Result: type a {normal, margin, stop}; 

TextBlt returns, in place of the argument pointer on the stack, an indication of its 
completion condition: normal if the last character was processed, margin if the right 
margin was reached (format only), and stop if a terminating character was detected. 

notlnFont is returned if the printer width for the character is a distinguished value 
(177777B). This allows the flags to be independent of the font and yet provides a way for 
information in the font to cause TextBlt to terminate. 

TextBlt.SoftwareTextBIt: procedure [ 

index: cardinal, bitPos: cardinal, micaPos: cardinal, count: integer, 
ptr: pointer to TextBltArg] 

RETURNS[ 

newlndex: cardinal, newBitPos: cardinal, newMicaPos: cardinal, 
newCount: integer, result: Result]; 

SoftwareTextBIt is a software version of TextBlt. It is useful on processors that do not have 
microcode support for the TextBlt operation described in this section. 

* 

2.2.3 Checksum 

Checksum definitions 

This interface produces a checksum for nWords starting at p. Changing the initial value 
cs is useful if forming a single checksum for discontinuous areas of memory. 

checksum.ComputeChecksum: proc [cs: cardinal «-0, nWords: cardinal, p: long pointer] 
returns [checksum: cardinal] ; 

Checksum. nullChecksum: cardinal = 177777B; 

This is a ones-complement add-and-left-cycle algorithm. 

2.2.4 ByteBIt 

ByteBIt: definitions ...; 

The only operation in this interface is ByteBIt which provides a Mesa definition of a byte 
boundary block transfer operation. It takes descriptions of two byte blocks as arguments, 
transfers as many bytes as possible (the min of the two lengths), and returns a count of how 
many bytes were actually moved. 

ByteBIt.ByteBlt: PROCEDURE [to, from: Environment.Block, 
overLap: ByteBit.OverLapOption] 

RETURNS [nBytes: cardinal]; 

ByteBit-OverLapOption: type = {ripple, move}; 
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ByteBlt.StartlndexGreaterThanStopIndexPlusOne: error; 

A length of zero in either to or from is acceptable, resulting in no transfer. If a negative 
length (startlndex J> stopIndexPlusOne) is present in either to or from, ByteBIt signals 
ByteBit.StartlndexGreaterThanStopIndexPlusOne. 

The OverLap argument defines the effect of ByteBIt when the source and destination fields 
overlap. If overLap is move then the contents of the source field are preserved by the 
move. It acts as if the two fields did not overlap. If overLap is ripple then a low address to 
high address move takes place with no notice taken of overlapping fields. This mode is 
useful for propagating a value throughout a block of storage. 

2.2.5 Other Mesa machine operations 
Inline: definitions...; 

This interface defines a set of instructions not directly accessible from Mesa. It includes 
some logical instructions and some extended-precision arithmetic instructions. 


2.2.5.1 Accessing parts of a word or double word 

The type Environment.LONG allows direct access to the high-order and low-order words of 
LONG values. For convenience, a copy of this type is available in the inline interface. 

inline.LongNumber: type = Environment.LongNumber; 

Alternatively, the following operations may be used: 

Inline.LowHalf: PROCEDURE [LONG UNSPECIFIED] RETURNS [UNSPECIFIED] 

inline. HighHalf: PROCEDURE [long unspecified] returns [unspecified] 

LowHalf and HighHalf return, respectively, the least and most significant words of its 
argument. 

Note: A long cardinal or long integer whose value is in cardinal or integer, respectively, 
may be directly converted to a short value using a mesa range assertion. 

The following procedures return the least and most significant bytes of a word, 
respectively. 

iniine.LowByte: procedure [unspecified] returns [unspecified] 
iniine.HighByte: procedure [unspecified] returns [unspecified] 

2.2.5.2 Copying blocks of words 

The following operations copy blocks of words. 

inline. copy: procedure [from: pointer, nwords: cardinal, to: pointer] 


i 
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inline.Longcopv: procedure [from: long pointer, nwords: cardinal, 
to: LONG pointer] 

miine.LongcoPYReverse: procedure [from: long pointer, nwords: cardinal, 
to: LONG pointer] 

COPY and LongcOPY copy nwords and are equivalent to the following Mesa code fragment: 

for i in [0..nwords) do (to + i) f <- (from + i) f endloop; 

LongCOPYReverse copies nwords and is equivalent to the following Mesa code fragment: 

FORi decreasing in [O..nwords) do (to+ i) | «- (from + i) f endloop; 

An upper limit of 65,535 words can be copied in any one call on Copy, LongCopy, or 
LongCopyReverse. 

Caution: Many errors in COPY, LongCOPY, and LongCOPYReverse are the result of an 
incorrect order of parameters. The keyword constructor call is recommended. 

2.2.5.S Special divide instructions 

All of the divide operations described in this section will raise the error 
Runtime.ZeroDivisor if the denominator is zero. All except for UDDivMod and SDOivMod, 
will raise Runtime.DivideCheck if the quotient is greater than 216-1 (see §2.4.3 for more 
information on these errors). 

The quotient and remainder of two cardinals or long cardinals can be obtained with the 
procedures 

Inline.DIVMOD: PROCEDURE [num, den: CARDINAL] 
returns [quotient, remainder: cardinal] 

inline.UDDivMod: procedure [num, den: long cardinal] 
returns [quotient, remainder: long cardinal]; 

where num is the numerator and den, the denominator. The procedure 

inline.LDiVMOo: procedure [numlow: word. numhigh: cardinal, den: cardinal] 
returns [quotient, remainder: cardinal] 

is the same as divmod except that the numerator is the double length number 

numhigh*2l6 + numlow. 

The operation 

mline.LongDiv: procedure [num: long cardinal, den: cardinal] 

RETURNS [CARDINAL] 

returns the single precision quotient of num by den. 
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If both the quotient and remainder of num and den are desired, the following operation 
can be used. 

iniine.LongDivMod: procedure [num: long cardinal, den: cardinal] 
returns [quotient, remainder: cardinal] 

The quotient and remainder of two long integers can be obtained with the procedure 

iniine.SDDivMod : procedure [num, den: long integer] 
returns [quotient, remainder: long integer]; 


2.2.5.4 Special multiply instruction 

The double precision product of two cardinals is obtained with 

Inline.LongMult: PROCEDURE [CARDINAL, CARDINAL] 
returns [product: LONG CARDINAL] 

2.2.5.5 Operations on bits 

The following operations perform the indicated bitwise logical operations on their 
operand(s): 

Inline. BitOp: TYPE ■ PROCEDURE [UNSPECIFIED, UNSPECIFIED] RETURNS [UNSPECIFIED]; 

Inline.BITAND, BITOR, BITXOR: inline.BitOp; 

Inline. DBitOp. TYPE a PROCEDURE [ LONG UNSPECIFIED, LONG UNSPECIFIED] 

RETURNS [LONG UNSPECIFIED], - 

Inline.DBITAND, DBITOR, DBITXOR: Inline.DBitOp; 

Inline.BITNOT: PROCEDURE [UNSPECIFIED] RETURNS [UNSPECIFIED] 

Inline.DBITNOT: PROCEDURE [LONG UNSPECIFIED] RETURNS [LONG UNSPECIFIED]; 

A word or double word can be shifted by the operations 

iniine.BITSHIFT: procedure [value: unspecified, count: integer] 

RETURNS [UNSPECIFIED] 

Inline.DBITSHIFT: PROCEDURE [value: LONG UNSPECIFIED, count: INTEGER] 

RETURNS [LONG UNSPECIFIED]; 

inline.BITROTATE: procedure [value: UNSPECIFIED, count: integer] 

RETURNS [UNSPECIFIED]; 

These operations return value shifted by ABSfcount] bits. The shift is left if count > 0, and 
right if count < 0. In both cases, zeros are supplied to vacated bit positions. In the case of 
BITROTATE, the bits are shifted circularly. 
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Note: A left shift is a multiply by two ignoring overflow; a right shift is an unsigned divide 
by two with truncation. 

2,3 System timing and control facilities 
System: definitions 
NSConstants: definitions 

This section describes some basic system and control facilities provided by Pilot. It 
introduces and discusses: universal identifiers, by which all network resources and other 
permanent objects in a network may be named; the means by which communicating 
processes are identified; the various forms of timekeeping provided by Pilot; the Pilot 
facilities for turning system power on and off; and how a client gets started. 

2.3.1 Universal identifiers 

A universal identifier may be used for naming all permanent or potentially permanent 
objects in the network. Every object and every resource may be assigned a separate, 
unique, universal identifier which is different from any other assigned for any other 
purpose. Thus, a particular universal identifier can be interpreted unambiguously in any 
context or on any processor, and it always refers to the same thing. 

Universal identifiers are 5word Mesa objects of the following type. 

System. UniversallD: type [5]; 

Pilot issues a new universal identifier, distinct from all others on all other processors at all 
times, as a result of the operation 

System. GetUniversallD: procedure returns [uid: System. UniversallD]; 

A UniversallD has no internal structure perceivable by client programs, and no properties 
must be attributed to values of this type except the property of uniqueness. Pilot takes 
extreme measures to ensure with a very high probability that UniversallDs are not 
duplicated. The supply of new universal identifiers is limited to an overall processor 
average of approximately one or a few per second, though the instantaneous rate of 
creating them can exceed this at times. If Pilot detects any danger of compromising the 
reliability of the uniqueness property, the process calling GetUniversallD is delayed until 
a new UniversallD can be safely issued. 

The following are some particular uses of UniversallDs: 

System.PhysicalVolumelD: type = record [System.UniversallD]; 

System. VolumelD: type = record [System. UniversallD]; 

System. nulllD: System. UniversallD * ...; 

Note: nulllD is never returned by GetUniversallD. 
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2.3.2 Network addresses 

The Internet Transport Protocols are the principal means of communication among 
processes which reside on different machines (see §6.2, Network streams). A source or 
destination of such communication is identified by its NetworkAddress. 

System.NetworkAddress: type « machine dependent record[ 
net: System.NetworkNumber, 
host: System.HostNumber, 
socket: System.SocketNumber]; 

System. NetworkNumber: type [2]; 

System. HostNumber: type [3]; 

System. SocketNumber: type [1J; 

System.nullNetworkAddress: System. NetworkAddress = 

System.nu 11 NetworkNumber: System.NetworkNurnber = .. .; 

System.nullHostNumber: System.HostNumber = ...; 

System.broadcastHostNumber: System.HostNumber a ...; 

System.nullSocketNumber: System.SocketNumber = .. 

System.localHostNumber: readonly System.HostNumber ; 

nullNetworkAddress is never used as a source or destination and so may be used when no 
valid address exists. 

nullNetworkNumber is normally not used as a source or destination. However, it can be 
used on networks that are unable to obtain a network number. 

localHostNumber is the HostNumber of the local machine. 

Within a processor, sockets are used to separate and identify communication meant for 
different purposes or destined for different processes. Sockets are associated with network 
addresses and are considered to be a reusable resource which is allocated as required. 

A NetworkAddress is normally retrieved from a Clearinghouse server. The network 
address of the local system element can be discovered with 
NetworkStream.AssignLocalAddress ( q.v .). Network addresses are guaranteed to be unique 
between system restarts, but not across system restarts, i.e., they are reused each time the 
system is restarted (see chapter 6). 

The case of network addresses of processors which are connected to more than one network 
is still to be determined. 
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2.3.3 Timekeeping facilities 

There are three forms of timekeeping facilities in Pilot: the date and time-of-day, the 
"stopwatch" or interval timing function, and the "alarm clock" facility. 

2.3.3.1 Time of day, and date 

The time and date are maintained by Pilot and the system hardware, typically in the form 
of an accurate, crystal-controlled clock. The following operations are used to access the 
clock: 

System. GetGreenwichMeanTime: procedure 
returns [gmt: System. GreenwichMeanTime]; 

System.GreenwichMeanTime: type * record [long cardinal]; 

System.gmtEpoch: System.GreenwichMeanTime = [ 2114294400 ]; 

System.SecondsSinceEpoch: procedure [gmt: System.GreenwichMeanTime] 
returns [long cardinal]; 

The gmtEpoch is equivalent to the following: 

(67 years * 365 days 4- 16 leap days) * 24 hours * 60 minutes *60 seconds 

The GetGreenwichMeanTime operation returns the time as a count of seconds since a 
fixed, arbitrary base time. In particular, 

gmt » t corresponds to the time t-System.gmtEpoch seconds after midnight, 1 
January 1968. That is, the time System.gmtEpoch +1 corresponds to 00:00:01, 
January 1, 1968 (i.e., one second after midnight, ten years prior to the first 
publication of the Pilot Functional Specification). 

The "end of time” occurs 232 seconds after 00:00:01 January 1, 1968. After the "end of 
time", new clock readings will not be valid. Two GreenwichMeanTimes can be compared 
directly for equality. To find which of two GreenwichMeanTimes comes first, apply 
SecondsSinceEpoch to each. This gives the number of seconds that each is after 00:00:00 
January 1, 1968. Finally, compare the results to determine which is the later time. That 
is, compare SecondsSinceEpoch [tl] to SecondsSinceEpoch [t2] and not tl to t2. 

System Extras. CIockFai led: signal; 

PilotSwitchesExtraExtraExtraExtras.ignoreClockFai lures: 

PilotSwitches.PilotDomainA * '.; 

Pilot periodically checks to see if the time-of-day clock is running correctly by 
GetGreenwichMeanTime. If it appears that it is not, the signal SystemExtras.ClockFailed 
will be raised. If the switch PllotSwitchesExtraExtraExtraExtras.ignoreClockFailures is down, 
however, the signal will not be raised. 
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This signal is resumable, but unless the client sets ignoreClockFailures, the signal will 
probably be raised again. 

The operation 

System.AdjustGreenwichMeanTime: procedure [ 

gmt: System.GreenwichMeanTime, delta: long integer] 
returns [System.GreenwichMeanTime]; 

has the result gmt + delta. If t is a GreenwichMeanTime then [t + delta] is the 
GreenwichMeanTime that is delta seconds after t. 

Within the range that they overlap, the times defined here and the Alto time standard 
assign identical bit patterns to a particular time. However, the Pilot standard runs an 
additional 67 years before overflowing. 

Client programs are responsible for converting between Greenwich Mean Time and local 
time, taking into account Daylight Saving Time, etc., (see the next section). 

The time and date is kept accurately (to within a few seconds per month) by the hardware 
and is adjusted as part of system maintenance. In addition, Pilot ensures that all 
interconnected system elements on an NS network agree about the current time within a 
few seconds of each other, and that they agree with an externally supplied timekeeping 
standard if one is available. Prior to calling the client during booting, Pilot ensures that 
the processor clock is set correctly. Utility Pilot clients, however, must set the processor 
clock prior to calling any Pilot operation. This is done by using the operations in the 
OthelloOps interface. If this is not done, the results of Pilot operations are unspecified. 

2.3.3.2 Local time parameters 

Client programs may obtain the parameters of the local time zone. In normal network 
configurations, Pilot finds the parameters from a server and remembers them in 
nonvolatile storage. (Currently it stores them in the root page of the system physical 
volume.) There is also an operation by which a client can set the parameters (typically on 
a stand-alone or server machine). The time zone parameters are represented as a record: 

System.LocalTimeParameters: type = machine dependent record [ 
direction(0:0..o): System.WestEast, 
zone(0:i..4): [0..12], 
zoneMinutes(i: 0 .. 6 ): [0..59], 
beginDST(0:5..i5): [0..366], 
endDST(i:7..i5): [0..366]]; 

System.WestEast: TYPE = MACHINE DEPENDENT {west(o),east(i)>; 

The fields zone, zoneMinutes, and direction together define the time zone as so many 
hours and minutes west or east of Greenwich. Normally zoneMinutes is zero, but there 
are a few places in the world whose local time is not an integer number of hours from 
Greenwich. beginDST gives the last day of the year on or before which Daylight Savings 
Time could take effect, where 1 is January 1 st and 366 is December 31 st (the 
correspondence between numbers and days is based on a leap year). Similarly, endDST 
gives the last day of the year on or before which Daylight Savings Time could end. Note 
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that in any given year, Daylight Savings Time actually begins and ends at 2 A.M. on the 
last Sunday not following the specified date. If Daylight Savings Time is not observed 
locally, both beginDST and endDST are zero. 

To find the local time zone parameters, a client calls 

System.GetLocalTimeParameters: procedure [ 
pvID: System. PhysicalVolumelD [nullID] ] 

returns [params: System. LocalTimeParameters]; 

System. LocalTimeParametersUnknowrv. error; 

This procedure returns the local time zone parameters provided that Pilot could determine 
them either by consulting a network time server during initialization or because they had 
been previously saved on the system physical volume by a call to SetLocalTimeParameters 
(see below). If the parameters cannot be determined in either of these ways, the error 
LocalTimeParameterslInknown is raised. A normal Pilot client should always default 
pvID. A UtilityPilot client, on the other hand, must specify the ID of the physical volume 
of the normal system drive, if the local time parameters are to be saved on the disk.. 

While it is normally unnecessary for a client to do so, the time zone parameters saved in 
nonvolatile storage on an individual workstation can be set by calling 

System.SetLocalTimeParameters: procedure [params: System.LocalTimeParameters, 
pvID: System.PhysicalVolurnelD [nullID]]; 

The main use for this procedure would be in a server, where a system administrator could 
set the time zone parameters at system initialization time, in response to an act of 
Congress, etc. Pilot guarantees the local time parameters are set from the network or from 
the physical volume on the local disk. In UtilityPilot, however, the client must set the 
parameters prior to the call on GetLocalTimeParameters. 

As with GetLocalTimeParameters, pvID should always be defaulted by a normal client. 
2«3.3.3 Interval timing 

It is frequently desired to measure elapsed time at the resolution of microseconds during 
the execution of programs. Such measurements can be used in controlling system 
behavior, analyzing program or system performance, and stimulating various other 
activities. In many cases, the processor underlying Pilot will not provide a timer with a 
resolution of one microsecond. As a result, Pilot would have to convert between processor 
dependent units and microseconds to provide a timing facility that measured in 
microseconds. In many cases, the overhead inherent in this conversion would be large 
enough to inhibit the timing of functions. For this reason, Pulses are provided: 

System. Pulses: type = record [pulses: LONG cardinal]; 

A Pulse is a processor dependent unit of time. The actual resolution and accuracy of Pulses 
is determined by the accuracy and resolution of the internal clocks of the processor. 
Typically, resolution of Pulses will be in the range 1 * 1000 microseconds and it will be 
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accurate to within 10% or better. The current value of the processor interval timer may be 
read by 

System.GetClockPulses: procedure returns [System. Pulses]; 

A client may convert between pulses and microseconds with the operations: 

System.PulsesToMicroseconds: procedure [p:System.Pulses] 
returns [m: System.Microseconds]; 

System.MicrosecondsToPulses: procedure [m.System. Microseconds] 
returns [p:System.Pulses]; 

System. Microseconds: type = long cardinal; 

System. Overflow: error; 

To perform accurate timings, the user should measure events in terms of Pulses and only 
convert to and from microseconds when it is absolutely necessary. In particular, Pulses 
should be the time units used in the inner loops of programs or in any place where time is 
critical. 

Conversion in one direction or the other may cause an overflow. When this happens, Pilot 
will raise the error Overflow. 

Caution: The error Overflow is not implemented in Pilot 11.0. 

The processor interval timer wraps around after a processor dependent period of time, 
typically greater than one hour. Thus, Pulses cannot be used to measure events with a 
duration in excess of the wrap around period. 


2.3.3.4 Alarm clocks 

An alarm clock facility is provided by the Mesa process mechanism. A timeout value may 
be assigned to any condition variable by means of the operation Process. SetTimeout (see 
§2.4.1.2). A process may then "go to sleep" for that period by executing a wait operation on 
that condition variable. When the timeout expires (or when a notify operation is executed 
on that condition variable, whichever comes first), the process awakens and continues 
execution. One convenient way for a process to wait when there is no requirement for a 
NOTIFY wakeup is to call Process. Pause (§2.4.1.6). 

The resolution of the process timer is on the order of 15-50 milliseconds. It has no accuracy 
whatsoever. Thus, a client process must check either the time of day, an interval timer or 
the processor timer if it needs to know the time accurately. 

2.3.4 Control of system power 

The following operations allow the processor to be turned on and off under program 
control. 
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System.PowerOff: procedure; 

This operation causes the machine to be turned off. It does not return. Pilot will cause all 
input/output activity to be suspended, purge all of its internal caches, force out all mapped 
spaces to their file windows, stop all processes from further execution, and cause the 
display to be turned off. The only way to recover from this operation is to turn the system 
power on and press the restart button. If there is no power relay, the system element 
remains turned on but executing no programs; a unique code is displayed in the 
maintenance panel in this situation. 

The operation 

System. SetAutomaticPowerOn: procedure [ 

time: System. GreenwichMeanTime, externalEvent: boolean]; 

sets the internal clock of the processor to automatically turn on the system power at or 
after time. If externalEvent is false, power is turned on at the specified time. If 
externalEvent is TRUE, power is turned on in response to the first external event occurring 
after the time specified by time. An external event is an electrical signal made available to 
the processor (e.g., the ringing signal of a data telephone). 

If power is already on when this operation would turn it on, there is no effect. The 
automatic power on facility may be reset by calling 

System. ResetAutomaticPowerOn: procedure; 

2.3.5 Pilot’s state after booting 

The device that the system was booted (loaded) from may be ascertained by referencing 

System.systernBootDevice: readonly System. BootDevice; 

System. BootDevice: type = record [device: Device.Type, index: cardinal]; 

Client programs can determine if they are running upon UtilityPilot with: 

System. isUtilityPilot: readonly boolean; 

Boot switches are used to transmit operational information from the booting agent (e.g., 
Othello) to the running boot file (see client documentation for definitions of applicable 
boot switches). The boot switches are made available as 

System. Switches: TYPE ■ PACKED ARRAY CHARACTER OF System. UpDown; 

System. UpDown: TYPE = machine dependent {up(0), down(1)}; 

System.switches: readonly System.Switches; 

System.defaultSwitches: System.Switches = ALL[up]; 

If a switch is down, then it is active; if a switch is up, then it is inactive. The value of 
switches is determined as follows. First, if the booting agent provides switches other than 
defaultSwitches, that value is used. Otherwise, if the boot file was constructed (by 


2-24 




Pilot Programmer’s Manual 


2 


MakeBoot) to contain other than defaultSwitches, that value is used. Otherwise, 

defaultSwitches is used. 

Switch assignments are made by the Manager of Operating Systems. Ranges of switches 
are allocated for Pilot, for the Mesa Development Environment, and for product systems. 
The following list enumerates those switches currently used by to Pilot and describes their 
significance. 

Value Meaning 

& Hang with a maintenance panel code in lieu of going to the debugger. 

0 Go to debugger as early as possible in Pilot initialization. 

1 Go to debugger as soon as all code is map-logged. 

2 Go to debugger just before calling PilotClient.Run. 

3 Simulate 192K memory size for a Dandelion with no display . 

4 Initialize scratch memory pages to zero. 

5 Go to the Ethernet for a debugger. 

6 Turn owner checking on for the system zones. 

7 Disable map logging (see below). 

8 Create a Pilot interrupt key watcher. 

9 Simulate 256K memory size for a Dandelion with display. 

: Go to the debugger as early in initialization of the File manager as possible. 

; Go to the debugger as early in the initialization of the VM manager as possible. 

< Pretend that there is no Ethernet 1 attached to the system element. 

= Do not initialize the Communication package at system start-up. 

> Pretend that there is no Ethernet attached to the system element. 

{ Set the VM backing file size to 750 pages (see below). 

| Set the VM backing file size to 1400 pages (see below). 

} Set the VM backing file size to 2000 pages (see below). 

T Turn checking on the for system zones. 

? Make loadstate resident (for debugging on Utility Pilot-based clients). 

[ Create a tiny heap, with tiny increment values. 

% Create a medium-size heap, with medium-size increment values (default). 

] Create a large heap, with large increment values). 

/360 Display error code, global frame, and pc on boot loader errors. 

/361 Transmit Ethernet packets using IEEE 802.2 Logical Link Layer protocol. 

/362 Accept packets from the Ethernet in either IEEE 802.2 Logical Link Layer 
or Ethernet version 1.0 format. 

/363 Transmit packets to hosts in the format that the receiver desires. 

/366 Hold back 48 pages of reserved display memory. 

/367 Hold back 64 pages of reserved display memory. 

/370 Bypass the debugger substitute by going to the real debugger. 

/371 Tile code with one page swap units. 

/372 Give display memory to Pilot for client use. 

/373 Give display memory to Pilot for client use if no bitmap display. 

/374 Allows special clients to set parameters of system zones 
/375 Disable map logging (see below). 

/376 Delete boot loader so that the memory that it uses can be recycled. 

Full map logging is the default case when Pilot is booted if there is a debugger present. 
Full map logging includes occasionally going to the debugger to clean up the log. A 
debugger is considered present if there is a debugger installed on a volume of type one 
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higher than that of the boot file, or if debugger pointers have been set in the boot file, or if 
a remote debugger is specified (boot switch ”5”). 

If there is no debugger present, map logging proceeds until the log file fills up and then 
logging is disabled. This situation may be forced by setting boot switch /375. Boot switch 
”7” will cause Pilot to stop map logging when PilotClient.Run is called (at key stop 2). This 
key switch overrides key switch /375. 

The VM backing file is the file which is used to provide the backing file for Pilot data 
spaces ( q.u .). Under normal circumstances, its size is a function of the size of the volume 
booted from. For some logical volumes the default size may be too small. In that event, the 
switches T*» ar *d ma y be used to specify the size of the backing file. 

2.4 Mesa run-time support 

This section describes low-level facilities used to support the execution of Mesa programs. 
It describes operations to support the Mesa process mechanism; facilities relating to Mesa 
program modules; traps, signals, and errors which may be generated by a Mesa program 
during execution; and finally, some miscellaneous interfaces. 

2,4.1 Processes and monitors 
Process: definitions 

Most aspects of processes and monitors are made available via constructs in the Mesa 
language and are described in the Mesa Language Manual . Some operations whose 
frequency of use does not justify such treatment are cast as procedures. 

When a process is FORKed, it is called a live process. When it has been JOiNed or when it has 
been detached and its root procedure has returned, it is called a dead process. Programs 
must take care not to use or retain copies of the PROCESS of a dead process. Since Pilot may 
reuse PROCESSes, any operation performed on the PROCESS of a dead process may mistakenly 
operate on a different process than the one intended, with unpredictable results. 

Most of the operations which take a PROCESS as an argument (join, Process.Abort, and 
Process.Detach) may generate the following signal: 

Process.InvalidProcess: error [process: process]; 

This signal indicates that the argument is not a live process. 

The argument of InvalidProcess is actually of type unspecified. This is necessary since 
there is no generic type which includes all PROCESS types, independent of their result types. 
The same is true of all arguments and results discussed in this section that would 
otherwise be of type PROCESS. 

A PROCESS can be checked for validity by the operation 

Process. ValidateProcess: procedure [unspecified] 
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If the argument does not represent a live process, Process.InvalidProcess will be raised. 
Otherwise, this operation just returns. 

Caution: Since Pilot may reuse PROCESSes, ValidateProcess applied to the PROCESS of a 
dead process may not raise InvalidProcess. Such a dangling reference will appear 
legitimate to ValidateProcess, but is almost certain to cause trouble for any client program 
that makes use of it. 

2.4.1.1 Initializing monitors and condition variables 

Every monitor lock and every condition variable must be initialized before it can be used. 
There are three cases: 

Any monitor lock or condition variable residing in a global frame will be initialized 
automatically when the program is STARTed. Any monitor lock or condition variable 
residing in a local frame will be initialized automatically when the procedure is 
entered. 

Any monitor lock or condition variable allocated dynamically by the NEW operator 
(from an uncounted zone or MDS zone) will be initialized automatically upon 
allocation. 

Any monitor lock or condition variable allocated dynamically by other than the new 
operator must be initialized by the programmer using the facilities described below. 

Caution: Using uninitialized monitor locks or condition variables, or reinitializing 
monitor locks or condition variables once they are in use, will lead to totally unpredictable 
behavior. 

The following operations are provided for initializing monitor locks and condition 
variables which are allocated dynamically by other than the new operator: 

Process.lnitializeMonitor: procedure [monitor: long pointer to monitorlock]; 

InitializeMonitor sets the monitor unlocked and the queue of waiting processes to empty. 
It may be called before or after the monitor data is initialized, but must be called before 
any entry procedure is invoked. Once use of the monitor has begun, the monitor must 
never be initialized again. 

Process.lnitializeCondition: PROCEDURE[condition: long pointer to condition, 
ticks: Process.Ticks]; 

Process.Ticks: type * cardinal; 

InitializeCondition sets the queue of waiting processes to empty and the timeout interval 
of the condition variable to the specified value, in units of "ticks” of the process timer 
clock. It may be called before or after the other monitor data is initialized, but must be 
called before any wait or notify operations are performed on the condition variable. Once 
use of the condition variable has begun, the condition variable must never be initialized 
again . 
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Clients may convert process timer ticks to or from milliseconds using the following 
operations: 

Process.Milliseconds: type = cardinal; 

Process.MsecToTicks: PROCEDURE [Process.Milliseconds] RETURNS [Process.Ticks]; 

Process.TicksToMsec: PROCEDURE [ticks: Process.Ticks] 

RETURNS [Process.Milliseconds]; 

For setting long timeout intervals, the following operation is provided: 

Process.Seconds: type * cardinal; 

Process.SecondsToTicks: procedure [Process.Seconds] 

RETURNS [Process.Ticks]; 

Caution: Due to the limited range of the process timer, the maximum timeout that 
maybe set is about 980 seconds (16 minutes). 

2.4,1.2 Timeouts 

Condition variables that are initialized automatically do not time out. The time out of any 
condition variable may be changed by the operation: 

Process.SetTimeout: procedure 

[condition: long pointer to condition, ticks: Process.Ticks]; 

The given timeout interval will be effective for all subsequent wait operations applied to 
the condition variable. This operation will not affect the timeout interval of any processes 
currently waiting on the condition variable. 

Process.DisableTimeout: procedure [long pointer to condition]; 

DisableTimeout sets the timeout interval for the condition variable to infinity. That is, a 
process waiting on the condition variable will never time out. This will be effective for all 
subsequent wait operations applied to that condition variable. This operation will not 
affect the timeout interval of any processes currently waiting on the condition variable. 

SetTimeout and DisableTimeout are the only operations that may be used to adjust the 
timeout interval of a condition variable once it has been used. In particular, 
InitializeCondition must not be used for this purpose. 

Caution: Since the Mesa processor reserves some distinguished values of Ticks for special 
purposes, the timeout interval of a condition variable should not be set via the Mesa 
construct: 

condition.timeout ticks. -WRONG 
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2.4.1.3 Forking processes 

There is a limit on the number of co-existing processes allowed by Pilot. Attempts to fork 
too many processes will result in the error 

Process.TooManyProcesses: error; 

This may be caught by a catch phrase on the FORK, or by a catch phrase in some enclosing 
context. 

The maximum number of coexisting processes is specified to MakeBoot when building a 
boot file. See the Mesa User's Guide for details. 

A process which is FORKed but will never be JOiNed should be detached using the operation 

Process. Detach: procedure [process]; 

This operation conditions the process such that when it returns from its root procedure, it 
will be deleted immediately. 

Caution: Note that a variable of type PROCESS does not return results. If the root procedure 
of a process does return results, it will be necessary to loophole the parameter to Detach. In 
those cases, care should be exercised because if the results returned take more than 12 
words of storage, the storage that contains the results (a local frame) will be discarded and 
the space will never be recovered. If there are 12 or less words of results, the results will be 
discarded and the storage recovered. 

A process may determine its own identity by invoking 

Process.GetCurrent: procedure returns [process]; 

2.4.1.4 Priorities of processes 

When a process is created with fork, it inherits the priority of the forking process. A 
process may change its own priority with the SetPriority operation. 

Process.SetPriority: procedure [Process.Priority]; 

Process.priority Background: readonly Process.Priority; 

Process.priorityNormal: readonly Process.priority; 

Process.priorityForeground: readonly Process.priority; 

Process.priority: type = [0..7]; 

Larger values of Priority correspond to higher priorities. Implementation restrictions 
make it necessary to limit ordinary client processes to three priority levels, defined via 
exported variables, which are listed above in order of increasing priority. SetPriority 
should only be given one of these three constants (or a value previously obtained from 
GetPriority, which will be equal to one of these constants). 


2-29 



2 


Environment 


If it is desired to fork a process which runs immediately at a higher priority than the 
parent process, the parent can set its own priority to the higher level, fork the new process, 
and then restore its own priority. 

A process may determine its own priority by calling 

Process.GetPriority: procedure returns [Process.Priority]; 

2.4.L5 Aborting a process 

A process can be aborted by calling the operation 
Process. Abort: procedure [process: unspecified]; 

The effect of this operation is to generate the error ABORTED the next time the process waits 
on any condition variable which has aborts enabled. If the process is already waiting, the 
error is generated immediately. 

ABORTED may be caught by a catch phrase on the wait, or by a catch phrase in an enclosing 
context. The catch phrase is executed with the corresponding monitor locked. 

The intended use of Abort is to provide a means whereby one process may request of 
another that the latter should stop what it is doing. An ABORTED signal may occur on any 
condition variable which has aborts enabled, and thus every monitor should either be 
protected by some catch phrase for it, or contain no condition variables which have aborts 
enabled. 

A pending abort may be canceled by calling the operation 
Process.Ca nee!Abort: procedure [process: unspecified]; 

A process may discover if there is an abort pending for it by the operation 
Process. AbortPending: procedure [] returns [abortPending: boolean]; 

When a condition variable is initialized, it has aborts disabled. A condition variable may 
be set to allow aborts by the operation: 

Process.EnableAborts: procedure [long pointer to condition]; 

If a process with an abort pending is currently waiting on the condition variable, 
EnableAborts will have no immediate effect on it. However, if the process times out or is 
NOTiFYed, it will be aborted at that time. 

It is sometimes desirable to avoid aborts while waiting on a given condition variable. This 
may be effected by using 

Process.DisableAborts: procedure [long pointer to condition]; 

Condition variables are initialized to have aborts disabled. If a process with an abort 
pending waits or is waiting on a condition variable, the abort will be delayed until the 
process waits on some other condition variable which has aborts enabled. 
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A process can be suspended for a specified number of ticks with the operation 
Process.Pause: procedure [ticks: Process.Ticks]; 

Pause waits with aborts enabled, and so may raise the error aborted. Note that monitor 
locks of the caller are not released during the pause. 

The Mesa process mechanism does not attempt to allocate processor time fairly among 
processes of equal priority. A process itself will yield the processor to other processes of 
equal priority whenever it faults, Pauses or waits. If a process does these things only 
rarely, it may be desirable for it to occasionally yield control of the processor by calling 

Process. Yield: procedure; 

This places the calling process at the rear of the queue of ready-to-run processes of the 
same priority. Thus, all other ready processes of the same priority will run before the 
calling process next runs. Note however, that these other processes may make arbitrarily 
little progress due to page faults, etc. 

The logical correctness of client programs must not depend on the presence or absence of 
calls to Yield. Priorities and yielding are not intended as a process-synchronization 
mechanism. They are only provided to assist in meeting performance requirements. 

2.4.2 Programs and configurations 

Runtime: definitions 

Programs may be validated by 

Runtime.ValidateGlobalFrame: procedure [frame: Runtime.GenericProgram]; 

Runtime. GenericProgram: type a long unspecified; 

Runtime.InvalidGlobalFrame: error [frame: Runtime.GenericProgram]; 

If frame is not valid, InvalidGlobalFrame is raised, frame may be either a program or a 
long pointer to frame[ < program >]. Normal usage requiresa loophole. 

Pointers to procedure activation records (local frames) may be validated by 

Runtime.ValidateFrame: procedure [frame: unspecified]; 

Runtime.InvalidFrame; error [frame: unspecified]; 

If frame is definitely not valid, InvalidFrame is raised, frame should be a pointer to 
frame[ <procedure>]). The checking done by ValidateFrame only verifies that frame 
looks like a valid local frame; it is not possible for it to verify that it actually is a valid local 
frame. 

Runtime. nullProgram: program = nil; 
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For backwards compatiblity, a null program constant is provided. New client code should 
just use NIL. 

The PROGRAM containing a PROCEDURE can be obtained using 

Runtime.GlobalFrame: procedure [link: Runtime.ControlLink] returns [program]; 
Runtime.ControlLink: type ■ long unspecified; 

ControlLink may be any procedure. Normal usage requires a loophole. If link is an 
unbound procedure, Runtime. UnboundProcedure is raised. Runtime. InvalidGlobalFrame may 
also be raised. 

A program which was created by new < program > may be deleted using 

Runtime. UnNew: procedure [frame: program]; 

UnNew deletes the program and reclaims its storage. All items which were exported by 
the program (procedures, variables, signals, and the program itself) become dangling 
references and should not be retained or used by any programs which imported them. If 
frame is not valid, Runtime. InvalidGlobalFrame is raised. If the program was not created by 
new < program > , the debugger is called. 

Caution: When a program is UnNewed, there must be no processes executing procedures 
in the program or expecting to return to procedures in it. Failure to observe this rule will 
lead to unpredictable behavior. 

Since UnNew may not be used while any processes are using a program, it is not possible 
for a process to UnNew the program in which it is currently executing. Since this is 
occasionally desirable, a special operation is provided: 

Runtime.SelfDestruct: procedure; 

SelfDestruct deletes the program that invokes it and then returns, with no results, to the 
first enclosing context which is not in the deleted program. All items which were exported 
by the program (procedures, variables, signals, and the program itself) become dangling 
references and should not be retained or used by any programs which imported them. 

Caution: Since SelfDestruct effects a return without results to the first enclosing context 
which is not in the deleted program, the procedure which was called from that context 
must be declared as having no results; otherwise a stack error will occur. 

Caution: When a program is SelfDestructed, there must be no other processes executing 
procedures in the program or expecting to return to procedures in it. Failure to observe 
this rule will lead to unpredictable behavior. 

The following operations are used to load configurations and programs. They are 
implemented by the object file Loader . bed. 

Runtime.RunConfig: PROCEDURE [ 

file: File-File, offset: Fiie.PageCount, codeLinks: boolean false]; 
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Runtime.LoadConfig: procedure [ 

file: Fiie.File, offset: Fiie.PageCourvt, codeLinks: boolean false] 

RETURNS [PROGRAM]; 

Runtime.NewConfig: procedure [ 

file: Fiie.File, offset: File.PageCount, codeLinks: boolean «- false]; 

Runtime.ConfigError: error [type: Runtime.ConfigErrorType]; 

Runtime.ConfigErrorType: type a { 

badCode, exportedTypeClash, invalidConfig, missingCode, unknown}; 
Runtime.VersionMismatch: signal [module: long string]; 

These operations load a configuration or program from the object file contained in file 
starting at page offset of the file, offset enables one to skip leader pages, pack many object 
files into one, etc. Each program in the object file will be loaded with code links if (1) 
codeLinks = true, and (2) the object file is a configuration, and (3) the program or a 
configuration containing the program specified LINKS: CODE, and (4) a configuration 
containing that configuration or program was packaged, or bound specifying code copying. 
If a program is loaded with code links, its links are written into the object file. The three 
operations differ as follows. LoadConfig loads the object file and returns a program. The 
PROGRAM is used to start the object file. If the object file is a configuration, program is one 
of the configuration’s control programs (= NIL if the configuration has no control 
programs); if the object file is not a configuration, program is the program itself. A 
subsequent START <program> will initialize the loaded programs (note that start nil is a 
no-operation). RunConfig both loads and starts the object file. NewConfig loads the object 
file and throws away the PROGRAM, thus preventing it from being explicitly started. Using 
NewConfig is only appropriate if the configuration does not require initialization; its use 
is not recommended. 

If an object file being loaded imports an interface item and there are several instances of 
that interface item being exported by already-loaded objects files, the import is bound to 
the most-recently loaded instance of the interface item. If an object file being loaded 
imports an interface item which it itself exports, the import is bound to the one it exports. 

If the object file being loaded imports or exports a version of a program which differs from 
a version exported or imported by already-loaded files, Runtime.VersionMismatch is raised, 
passing the name of the offending program. Resuming this signal allows loading to 
proceed; the imported items with mismatched versions remain unbound. The signal is 
raised once for each mismatch encountered. 

Note: If VersionMismatch is resumed, the system will be exporting two different versions 
of various programs. Object files loaded subsequently which import these programs may 
get VersionMismatch against the "bad” version; however, if the signal is resumed and the 
correct version is found, the desired binding will be done. 

If the code for any of the programs is not contained in the object file (typically because a 
configuration was not bound with code copying), Runtime.ConfigError[missingCode] is 
raised. If the object file exports a type that differs from that exported by an already loaded 
program, Runtime.ConfigError[exportedTypeClash] is raised. If any program in the object 
file is loaded with code links but the volume containing file is read-only, Volume. Readonly 
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is raised. If the object file contains a definitions module, is not compatible with the current 
version of Mesa, or is not an object file at all, Runtime.ConfigError[invalidConfig] is raised. 
If the object file is not completely contained in the file, Space. Error[noWindow] is raised. 
Any of the errors raised by Space. Map may also be raised. ConfigErrorTypes of badCode 
and unknown are not used at present. 

Caution: If a program in the boot file imports an item which is satisfied by a 
configuration which is loaded at run-time, the importing program must have frame links. 
If this rule is not followed, the link to the imported item will be written into the boot file, 
and will be a dangling reference when the boot file is invoked at later times. 

A object file which was loaded at run-time may be unloaded by 

Runtime.UnNewConfig: procedure [link: Runtime.ControlLink]; 

UnNewConfig unloads the dynamically-loaded object file associated with link, link may be 
any PROCEDURE or program in the object file. UnNewConfig frees the storage of all 
PROGRAMS of the object file, and unmaps and deallocates the virtual memory containing its 
code. All items that were bound to the object file are reset to unbound. 

Caution: When an object file is UnNewConfiged, there must be no processes executing 
procedures in programs of the object file or expecting to return to procedures in them. 
Failure to observe this rule will lead to unpredictable behavior. 

The time at which the currently running boot file was built by MakeBoot is returned by 

Runtime.GetBuildTime: procedure returns [System. GreenwichMeanTime]; 

The time at which a configuration was bound is returned by 

Runtime.GetBcdTime: procedure returns [System. GreenwichMeanTime]; 

This operation returns the bind or compile time of the outermost configuration containing 
the caller of GetBcdTime. If there are no containing configurations, GetBcdTime returns 
the compile time of the caller. 

The next two operations are useful for debugging and determining what has been loaded. 

Runtime.GetCaller: procedure returns [program]; 

GetCaller returns the program that called the client's program. More precisely, it returns 
the PROGRAM of the innermost enclosing context which is outside the PROGRAM that 
contains the procedure called GetCaller. 

Runtime.lsBound: PROCEDURE [link: Runtime.ControlLink] RETURNS [boolean]; 

IsBound returns true if the imported procedure link is bound (i.e., if link is being exported. 
Normal usage requires a loophole, link may also be an imported variable or an imported 

PROGRAM. 

Caution: Unexpected results can be experienced using code links, run-time loading and 
IsBound. In particular, if a program in the boot file is loaded with code links and imports 
an item which is satisfied by a configuration which is loaded at run-time, the program will 
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have links which appear to be bound but are actually left over from a previous boot 
session. Boot file importers of unbound items should be bound with frame links. 

A pointer to the data portion of a program compiled with the Table Compiler is returned 
by 

Runtime.GetTableBase: procedure [frame: program] returns [long pointer]; 

GetTableBase may raise Runtime.InvalidGlobalFrame. 

2.4.3 Traps and signals 

Programming errors and other errors encountered by Mesa programs result in signals or 
errors. The first five errors described below are related to specific language features and 
are described in more detail in the Mesa Language Manual. 

Runtime. StartFault: error [dest: program]; 

StartFault is raised if dest was STARTed but it had been started previously (perhaps by a 
start trap), or if dest was RESTARTed but it had not STOPped. 

Note: If a program does start <program> but program is not valid, 
Runtime.InvalidGlobalFrame is raised. This will happen if program is an unbound import. 

Runtime.ControlFault: error [source: Runtime. ControlLink]; 

ControlFault is raised if a program attempts to transfer to a null control link while 
executing in the local frame denoted by source. This error passes the control link that was 
used. In the current version of Mesa, ControlFault may be raised on an attempt to call an 
unbound procedure (instead of UnboundProcedure). 

Runtime. UnboundProcedure: error [dest: Runtime. ControlLink]; 

UnboundProcedure is raised if a program attempts to call an unbound procedure. This 
error passes the procedure that was called. 

Caution: In the current version of Mesa, ControlFault may be raised instead of 

UnboundProcedure. 

Runtime. LinkageFault: error; 

A transfer has been attempted through a port that has not been connected to some other 
port or procedure (the link field of the port was nil). 

Runtime. PortFault: error; 

A transfer has been attempted to a port which is not pending (the frame field of the 
destination port is nil). This error is used to handle the transients normally occurring 
while initializing coroutines. 

BoundsFault: signal; 
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A value being assigned to a subrange variable or being used in an indexing operation was 
out of range. This signal may also be raised if an attempt is made to assign a signed value 
to an unsigned variable and vice versa. This signal is only raised by programs which have 
been compiled specifying bounds checking. RESUMEing this signal will allow the program to 
use the illegal value, with unpredictable results. 

NarrowFault: error; 

An attempt was made to use the narrow operator on a value x to make it of type T, but the 
type of the value of x was some other. For example, an attempt was made to narrow a 
(pointer to a) variant record to a (pointer to a) specific variant, but the value of x was some 
other variant. 

PointerFault: signal, 

An attempt has been made to dereference a nil pointer. This signal is only raised by 
programs which have been compiled specifying nil checking. RESUMEing this signal will 
use the nil value, almost invariably causing an immediate address fault. 

Note: Pilot leaves virtual address nil | and long nil t unmapped. Attempts to dereference 
a nil pointer will usually cause an address fault. 

Runtime.ZeroDivisor: signal; 

An attempt was made to divide by zero. If this signal is RESUMEd, the result of the divide 
operation is undefined. 

Runtime.DivideCheck: signal; 

An attempt was made to perform a division involving LONG operand(s) whose result could 
not be expressed in a single word. If this signal is RESUMEd, the result of the divide 
operation is undefined. 


2.4.4 Calling the debugger or backstop 

A program can explicitly invoke the debugger or backstop by calling 
Runtime.CallDebugger: procedure [long string]; 

Client program execution is suspended. The debugger prints the string provided and 
awaits user commands. A Proceed command resumes client program execution after the 
call to CallDebugger. (If continuing execution at this point is not reasonable, the call to 
CallDebugger should be placed inside a non-terminating loop.) 

A program may also invoke the debugger or backstop by calling 

Runtime.lnterrupt: procedure; 

The debugger prints "*** Interrupt ***" and awaits user commands. Interrupt is typically 
called by a user input handling process in response to some user action such as typing a 
special keyboard key. 
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2.5 Client startup 

PilotClient: definitions ...; 

Pilot imports precisely one client interface, called PilotClient. The PilotClient interface is 
defined as follows: 

PilotClient: definitions * 

BEGIN 

Run: procedure []; 

END. 

The client configuration must export a PROCEDURE called PilotClient. Run. Pilot initializes 
itself and without explicitly STARTing any client programs calls Run, the first client 
procedure, as follows: 


Process.SetPriority[Process.priorityNormal]; 
Process.Detachf FORK PilotClient. Run[] ]; 


This will cause a start trap within the program containing Run, and will thus start the 
control module(s) of the containing configuration, if any. Run is responsible for loading 
and starting all client programs, creating spaces, forking processes, etc. It may freely use 
the Mesa new statement, refer to any known file, and use any facility of Pilot. It may or 
may not have a user interface, depending upon the application it implements. 

2.6 Coordinating subsystems’ acquisition of resources 
Supervisor: definitions 
SupervisorEventlndex: definitions 

This interface provides a facility for notifying interested clients of events which typically 
have a fairly widespread impact. The Supervisor can be used for managing the orderly 
acquisition and release of shared resources such as a file, a removable volume, or, in the 
case of restarting the machine from a restart file, the entire processor. The Supervisor 
facility has some similarities to the Ethernet, in that it provides a way to broadcast 
information (within a single processor) to an expandable collection of interested client 
software. 

The Supervisor accommodates a model of the entire client system as a collection of 
subsystems which depend on some basic resource. To handle this model, the Supervisor 
maintains a database which describes dependency relationships, and provides a way to 
invoke the subsystems in a clients-flrst or implementors-first order. 

Consider the event where a user indicates that he wants to withdraw a removable volume 
from a system element. The subsystems which are using the volume must release it in an 
orderly manner. Since the volume typically will be used by lower-level subsystems to 
build higher-level abstractions for its clients, the higher-level abstractions must also be 
released, and indeed must be released before the lower-level subsystem may release the 
volume. Thus, the releasing of a volume should normally proceed in a clients-flrst order. 
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Similarly, when a volume is added to a system, the subsystems which would like to use it 
should acquire it in an orderly manner, typically implementing subsystems first. 

Events for which the Supervisor may be useful include: 

• Making a restart file. 

• Restarting the system element from a restart file. 

• Removing or adding a physical or logical volume. 

• Turning power off (possibly with Automatic Power On enabled). 

• The appearance/disappearance of some service or resource on this or another system 
element. 

The implementation module is Supervisorlmpl. bed. 

2.6.1 Use of the Supervisor 

Each subsystem should obtain a subsystem handle from the Supervisor and export it to its 
clients. The handles are used by clients to declare, to the Supervisor, which subsystems 
they depend on. Each subsystem also registers an agent procedure. When an interesting 
event happens, the Supervisor is invoked to notify, in proper order, the agent procedures of 
all subsystems, informing them of the event. Upon return from this enumeration, all 
subsystems will have been notified of the event. 

Since several lowest-level subsystems may utilize the same basic resource, the event of 
releasing a resource might be organized as follows: the enumeration would have each 
subsystem release its use of the resource, and then the caller of the enumeration would 
actually release the basic resource. 

On the other hand, acquisition of a new resource is slightly different. The enumeration 
would declare the availability of a new resource. The lowest level subsystems might 
implement some higher-level resource on it, and then that subsystem’s clients could 
interrogate it for the new resources when their agent procedures were called. 

For example, in the event of removing a physical volume from the system element, the 
agent procedure for a subsystem might perform the following actions: 

1. Put the subsystem’s processes to sleep, or into some quiescent state; 

2. Browse through the subsystem’s database and locate any objects which were built 
upon files residing on the physical volume to be removed; this step may well involve 
calls to some lower-level subsystems to determine the physical location of their 
objects; 

3. Delete or otherwise make inactive any objects based on these files and update the 
database accordingly; 

4. Reawaken its processes; 
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5. Return. 

The enumeration of subsystems is typically invoked from a very high level, not from 
within a monitor implementing a resource which is acquired or released. 

2.6.2 Supervisor facilities 

An Event is a value that names a particular event in which some subsystems may be 
interested. 

Supervisor.Event: type = record [eventlndex: Supervisor.Eventlndex]; 

Supervisor.Eventlndex: type = cardinal; 

Supervisor, null Event: Supervisor.Event = Supervisor.Event[LAST[Supervisor.Eventlndex]]; 

The domain of Event is shared by all of the Supervisor’s clients, who therefore must agree 
on the meaning of the values. If some software that uses events runs in several disparate 
systems (e.g., Star and Tajo), then those systems must agree on the values of the events 
which are common to both systems. In this case, there is a common definitions module, 
SupervisorEventlndex, which defines subdomains for those events common to each 
system, and subdomains for those events unique to each system. Also disallowed is the 
defining of one element of Event to correspond to more than one event. That is, there 
cannot be any catch-all Events. 

The basic structure of the SupervisorEventlndex interface is a set of subrange definitions. The 
following ranges are defined. 

SupervisorEventlndex. Eventlndex: TYPE a Supervisor.Eventlndex; 

SupervisorEventindex.MesaEventlndex: TYPE = CARDINAL [0..1024]; 

SupervisorEventlndex.CommonSoftwareEventlndex: TYPE a CARDINAL [1024..1280]; 

MesaEventlndex's are used by Mesa source and object files. 
CommonSoftwareEventlndex's are used by product common software. 

Note: Each client of SupervisorEventlndex interface should maintain an interface which 
defines the Events in its subrange. 

Each software component or subsystem which is interested in events should register an 
AgentProcedure, which will be called when events occur: 

Supervisor.AgentProcedure: type = procedure [event: Supervisor.Event, 

eventData: long pointer to unspecified, instanceData: long pointer to unspecified]; 

Supervisor.nullAgentProcedure: Supervisor.AgentProcedure ■ nil; 

When an agent procedure is called, it should first examine event, and ignore ones which it 
does not recognize or care about. The agent procedure may use facilities upon which it 
depends (see DependsOn below). eventData is supplied by the software that caused the 
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notification of the event, and its interpretation depends on event. eventData might be 
declared as 

eventData: long pointer to record [select computed event.eventlndex from ... endcase; 

instanceData is supplied when the agent procedure is declared to the Supervisor, and may 
be used to convey to the agent procedure any data necessary for a particular instance of its 
parent program. An AgentProcedure of nil may be used for subsystems which do not wish 
to have an associated agent procedure. For backwards compatiblity, a null 
AgentProcedure constant is provided. New client code should just use nil. 

The client's AgentProcedure must not call back into the Supervisor, either directly or 
indirectly, as this will cause the containing process to hang on a monitor lock. 

To participate in the event mechanism, each implementing subsystem must register itself 
with the Supervisor. When it does, the Supervisor returns a SubsystemHandle, which is 
used to identify the subsystem to the Supervisor, and to the subsystem's clients. 

Supervisor.SubsystemHandle: type [1]; 

Supervisor.nullSubsystem: readonly Supervisor.SubsystemHandle; 

Supervisor.CreateSubsystem: procedure [ agent: Supervisor.AgentProcedure *-nil, 
instanceData: long pointer to unspecified nil] 
returns [handle: Supervisor.SubsystemHandle]; 

This operation creates a new subsystem object and causes an agent procedure and a set of 
instance data to be associated with it. The returned subsystem handle typically is made 
available to the subsystem's clients. The agent procedure for the subsystem will be called 
when events happen, passing instanceData to it at that time. 

A subsystem is deleted by 

Supervisor.DeleteSubsystem: procedure [handle: Supervisor.SubsystemHandle]; 
Supervisor.InvalidSubsystem: error; 

InvalidSubsystem is raised if handle does not describe a valid subsystem. Clients must 
take care to not retain nor use the SubsystemHandle of a deleted subsystem. 

Operations are provided for declaring the dependency relationships between subsystems, 
and for inquiring about current dependencies: 

Suporvisor.AddDependency: procedure [client, implementor: Supervisor.SubsystemHandle]; 
Supervisor.CyclicDependency: error; 

Supervisor.RemoveDependency: procedure [client, implementor: 

Supervisor . Su bsy ste m H a n d I e]; 

Supervisor.NoSuchDependency: error; 



Pilot Programmer’s Manual 


2 


AddDependency declares that client is directly dependent on implementor and directly 
uses its services. Typically, this declaration is made because a client subsystem needs to 
act on some event either before or after the subsystems which he depends on act on it. 
Duplicate direct dependencies are ignored. If implementor is already registered as being 
directly or indirectly dependent on client, CyclicDependency is raised. If client or 
implementor do not describe a valid subsystem, Supervisor.InvalidSubsystem is raised. 

RemoveDependency declares that client is no longer directly dependent on implementor. 
If client was not directly dependent on implementor, NoSuchDependency is raised. If 
client or implementor do not describe a valid subsystem, Supervisor.InvalidSubsystem is 
raised. 

Supervisor.DependsOn: procedure [client, implementor: Supervisor.SubsystemHandle] 
RETURNS [boolean]; 

DependsOn returns TRUE if and only if client is directly or indirectly dependent on 
implementor. If either client or implementor does not describe a valid subsystem, 

Supervisor.InvalidSubsystem is raised. 

When an event happens, the client program that caused the event notifies the registered 
subsystems with the following operation: 

Supervisor.NotifyAllSubsystems: procedure [event: Supervisor.Event, 

eventData: long pointer to unspecified, whichFirst: Supervisor.ClientslmpIs]; 

Supervisor.ClientsImpIs: type = {clients, implementors}; 

This operation calls the agent procedures of all subsystems. If whichFirst is clients, a 
subsystem is notified only after all of its clients have been notified. If whichFirst is 
implementors, a subsystem is notified only after all of its implementors have been 
notified. See the definition of AgentProcedure for a description of eventData. If a 
subsystem handle does not describe a valid subsystem, Supervisor.InvalidSubsystem is 
raised. 

Caution: No client of Tajo, CoPilot, or the Development Environment, versions 11.0, 
should call NotifyAHSubsystems. It will cause these systems to crash or hang. 

For events which are only of interest to a separable set of subsystems and for which it is 
desired to avoid swapping in the code of all agent procedures, NotifyRelatedSubsystems 
may be used. 

Supervisor.NotifyRelatedSubsystems: procedure [event: Supervisor.Event, 

eventData: long pointer to unspecified, which, whichFirst: Supervisor.ClientslmpIs, 
subsystem: Supervisor.SubsystemHandle]; 

This operation calls the agent procedures of all subsystems which are directly or indirectly 
clients or implementors of subsystem. For which equal to clients, it calls all agent 
procedures which are direct or indirect clients of subsystem. For which equal to 
implementors, it calls all agent procedures which are the direct or indirect implementors 
of subsystem. For whichFirst equal to clients, it visits a subsystem only after all of its 
clients have been visited. For whichFirst equal to implementors, it visits a subsystem only 
after all of its implementors have been visited. See the definition of AgentProcedure for a 


2-41 




2 


Environment 


description of eventData, If subsystem does not describe a valid subsystem, 

Supervisor.InvalidSubsystem is raised. 

Caution: NotifyRelatedSubsystems is not implemented in Pilot 11.0. 

For events which are only of interest to the immediate clients or implementors of a 
subsystem and for which it is desired to avoid swapping in the code of all agent procedures, 

NotifyDirectSubsystems may be used. 

Supervisor.NotifyDirectSubsystems: procedure [event: Supervisor.Event, 

eventData: long pointer to unspecified nil, which: Supervisor.ClientsImpIs, 
subsystem: Supervisor.SubsystemHandle]; 

This operation calls the agent procedures of all subsystems which are directly related to 
subsystem. For which equal to clients, it calls the agent procedures of all subsystems 
which are direct clients of subsystem. For which equal to implementors, it calls the agent 
procedures of all subsystems which are direct implementors of subsystem. See the 
definition of AgentProcedure for a description of eventData. If subsystem does not 
describe a valid subsystem, Supervisor.InvalidSubsystem is raised. 

2.6.3 Exception handling 

Handling recoverable error conditions encountered during an enumeration of subsystems 
requires some special consideration. Exceptions in Mesa are usually handled by signals. 
In the context of the Supervisor, these are not appropriate since the subsystems are 
enumerated sequentially, not recursively, and therefore the previously-invoked agent 
procedures are not in a position to catch a signal or an unwind. 

Thus, the following procedure is suggested: The agent detecting an error condition would 
signal an error to the caller of NotifyxSubsystems. That caller would catch the signal, 
unwind, and then call NotifyxSubsystems for an inverse event to the one being aborted. 
Thus, each agent would then be given the chance to back out of any actions he had taken. 
If there is no naturally-occurring inverse event, an artificial one can be defined 
specifically for backing out of particular kinds of aborted events. In some cases, a two- 
phase protocol may be necessary to handle an event properly. 

If no special information needs to be communicated while aborting an enumeration, the 
following signal may be used: 

Supervisor.EnumerationAborted: error; 

The caller of the enumeration should catch it. 

2.7 General object allocation 

ObjAlloc: DEFINITIONS 

This section describes the facility used to control the allocated/free state of a collection of 
objects. A typical application of this facility would be a storage allocator using ObjAlloc to 
manage its underlying database. 
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2.7.1 Basic types 

ObjAHoc.AllocFree: type = machine dependent {free(O), alloc(l)}; 

ObjAlloc.AllocationPool: type = packed array [0..0) OFObjAlioc.AllocFree; 

ObjAiioc.AllocPoolDesc: type ■ record [allocPool: long pointer to ObjAlloc.AllocationPool, 
poolSize: ObjAHoc.ltemCount]; 

ObjAHoc.Interval: type ■ record [first: ObjAHoc.ltemlndex, count: ObjAHoc.ltemCount]; 
ObjAHoc.ltemlndex: type = long cardinal; 

ObjAHoc.ltemCount: TYPE a LONG CARDINAL; 

An ObjAlloc.AllocationPool describes the allocated/free state of an ordered set of objects. 
Each object is identified by a name, called an ObjAHoc.ltemlndex. The location and size of 

an ObjAlloc.AllocationPool is given by an ObjAiioc.AllocPoolDesc. 

Note: The location must be word aligned, and the size is given in terms of the number of 
objects in the pool. 

An ObjAHoc.Interval describes a range of objects by giving the ObjAHoc.ltemlndex of the first 
object, and the number of objects in the range. 

2.7.2 Basic procedures and errors 

ObjAHoc.Allocate: procedure [ pool: ObjAiioc.AllocPoolDesc, count: ObjAHoc.ltemCount, 
willTakeSmaller: boolean <-false] returns [interval.ObjAHoc.Interval]; 

ObjAHoc.Error: error [error: objAlloc.ErrorType]; 

ObjAHoc. ErrorType: type = {insufficientSpace, invalidParameters}; 

ObjAHoc.Allocate finds, and marks as allocated, a range of count objects. If willTakeSmaller 
is false and count contiguous objects can not be found, ObjAHoc.Error[insufficientSpace] is 
raised. If willTakeSmaller is true, ObjAHoc.Allocate will allocate the largest range of objects 
whose size does not exceed count. In this case, ObjAlloc.Error[insufficientSpace] will only be 
raised if no free objects can be found. In either case, the returned range is guaranteed to be 
the range with the smallest first name that meets the needs inferred by count and 
willTakeSmaller. 

ObjAHoc.ExpandAllocation: procedure [ pool: ObjAiioc.AllocPoolDesc, 
where: ObjAHoc.ltemlndex, count: ObjAHoc.ltemCount, 

willTakeSmaller: boolean <-false] returns [extendedBy.ObjAHoc.ltemCount]; 

An allocated range can be expanded using ObjAHoc.ExpandAllocation. If the objects 
[where..where ♦ count) are all free, they are marked as allocated, and extendedBy is set 
to count. If only the objects [where..where + countFree) are free, where 
0< * countFree<count, the result depends upon the value of willTakeSmaller. If 
willTakeSmaller is false, extendedBy is returned as zero and no objects are marked 
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allocated. If willTakeSmaller is true, the objects [where..where + countFree) are marked 
as allocated and extendedBy is returned as countFree. 

ObjAHoc.Free: procedure [pool: ObjAHoc.AllocPoolDesc, interval: ObjAiioc.Interval, 
validate:BOOLEAN <-trueJ; 

ObjAiioc. Already Freed: error [item: ObjAHoc.ltemlndex]; 

A range of objects is freed by calling ObjAHoc.Free. If not all of the named objects are 
contained in pool, ObjAlloc.ErrorfinvalidParameters] is raised and no objects are marked 
free. If validate is true then an attempt to free an already free object results in the signal 
ObjAlloc.AlreadyFreed[item] being raised, with item as the smallest index of a free object in 
the interval. No objects are freed in this case. If validate is FALSE, the specified objects are 
marked as free with no checking performed. 

ObjAiioc.lnitializePool: procedure [ pool: ObjAHoc.AllocPoolDesc, initialState: 
ObjAHoc.AllocFree]; 

An ObjAlloc.AllocationPool may be initialized by calling ObjAiioc.lnitializePool. It will set 
the initial state of all of the objects in the pool to the specified state. 

Note: In any call to ObjAiioc.Allocate, ObjAlloc.ExpandAllocation, ObjAHoc.Free, or ObjAiioc. 
InitializePool, an ADDRESS fault may result if any part of the allocation pool is unmapped. 
Additionally, it is the clients responsibility to serialize access to the database. ObjAiioc 
provides no serialization. 
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Stream: definitions ...; 

The Stream Facility described in this section provides to Pilot clients a convenient, 
efficient, device- and format-independent interface for sequential access to a stream of 
data. In particular: 

It provides a vehicle by which processes or subsystems can communicate with each 
other, whether they reside on the same system element or on different system 
elements. 

It permits processes or subsystems to transmit arbitrary data to or from storage media 
in a device-independent way. 

It defines a standard way for transforming the detailed interface for a device into a 
uniform, high level interface which can be used by other client software. 

It provides an environment for implementing simple transformations to be performed 
on the data as it is being transmitted. 

It provides optional access to and control over the mapping of data onto the physical 
format of the storage or transmission medium being used. 

The stream package provides several facilities, not all of which may be important to an 
individual client. First, there is the stream interface , the set of procedures and data types 
by which a client actually controls the transmission of a stream of information. Each of the 
operations of the stream interface takes as a parameter a Stream. Handle which identifies 
the particular stream being accessed. Second, the stream package defines the concepts of 
transducer and filter. A transducer is a software entity ( e.g ., module or configuration) 
which implements a stream connected to a specific device or medium. A filter also 
implements a stream, but only for the purpose of transforming, buffering, or otherwise 
manipulating the data before passing it on to another stream. Transducers and filters may 
be provided either by Pilot or by clients. Third, the stream package provides a standard 
way of concatenating a sequence of filters (usually terminated with a transducer) to form a 
compound stream called a pipeline. A pipeline is accessed by means of the normal stream 
operations, and causes a sequence of separate transformations to be applied to data 
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flowing between the client program at one end and the physical storage (or transmission) 
medium at the other. 

Pipelines permit clients to interpose new stream manipulation programs (filters and 
transducers) between clients (producers and consumers of data) without modifying the 
interfaces seen by the clients. For example, a data format conversion program can obtain 
its data either from a magnetic cassette or from a floppy disk, using the same stream 
interface, and hence the same program logic, for both. Similarly, filters performing such 
functions as code conversion, buffering, data conversion, and encryption, may be inserted 
into a pipeline without affecting the way the client sends and receives data through the 
stream interface. 

The stream facility transmits arbitrary data, regardless of format and without prejudice to 
its type or characteristics. The data may comprise a sequence of bytes, words, or arbitrary 
Mesa data structures. The stream facility does not presume or require the encoding of 
information according to any particular protocol or convention. Instead, it permits clients 
to define their own protocols and standards according to their own needs. 

In this chapter, sections 3.1, 3.2, and 3.3 will be of interest to all clients. Section 3.4 will be 
of interest only to those clients wishing to control the physical record characteristics of a 
particular stream. Section 3.5 will be of interest only to those clients wishing to 
implement their own filters or transducers. In addition, the clients of a particular stream 
type (e.g., disk, tape) will normally have to consult separate documentation regarding the 
details of that kind of stream. 

3c 1 Semantics of streams 

The stream facility supports transmission of a sequence of eight-bit bytes. This sequence 
may be divided into identifiable subsequences , each of which has its own subsequence type . 

Stream. Byte: TYPE a Environment. Byte; 

Environment.Byte: TYPE = [0..256); 

stream.SubSequenceType: type = [0..256); 

A subsequence may be null: i.e., it may be of zero length and contain no bytes but still 
contain the SubSequenceType information. This information allows all subsequences to 
be easily identified and separated from each other while shielding clients from the 
bothersome problems of control-codes (i.e., embedding control codes into the stream, 
making them transparent, and building a parser to implement such transparency). 

Additionally, an attention flag may be inserted into a stream sequence. Attention flags are 
transmitted through the stream as quickly as possible, possibly bypassing bytes and 
changes in SubSequenceType which were transmitted earlier but which are still in 
transit. This provides a simple mechanism for implementing breaks (similar to the 
"attention-key’ 1 of many time-sharing systems). A byte of data is associated with an 
attention flag for the use of client protocols. Note that the attention flag and the data byte 
occupy a byte in the stream sequence. 

Streams have no intrinsic notion of the bytes passing through them being grouped into 
physical records. The client program can completely ignore physical record structure and 
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is thus relieved of the burden of dealing with the associated packing and unpacking 
problems. If, however, it becomes necessary to control or determine the underlying 
physical record structure, as determined by the particular storage (or transmission) 
medium, the interface provides extended facilities which allow this. 

All of the procedures described here are synchronous. That is, an input operation does not 
return until the data is actually available to the client, and an output operation does not 
return until the data has been accepted by the stream and client buffers may be reused. 
Note, however, that a stream component may do internal buffering and that the 
acceptance of data means only that the stream component itself has a correct copy and is in 
a position to proceed asynchronously to write or send it. 

Streams in Pilot are inherently full duplex. Separate processes may be transmitting and 
receiving simultaneously. The stream interface does not guarantee mutual exclusion 
among different processes attempting to access the same stream. However, individual 
transducers or filters may restrict themselves to half duplex operation and may 
implement such mutual exclusion or more elaborate forms of synchronization as is 
appropriate. Documentation for such filters and transducers should be consulted on a case- 
by-case basis for details. 

3.2 Operations on streams 

The stream interface provides operations for sending and receiving data, for sending state 
information, and for dealing with stream positions. In addition, a Delete operation is 
provided to delete a stream. A create operation is not provided. Streams are only created 
by individual stream components, namely, pipelines, transducers and filters. 

A client program identifies a particular instance of the stream interface by means of a 

Stream. Handle. 

Stream. Handle: TYPE = ...; 

A Stream. Handle identifies an object (see §3.5.1) which embodies all of the information 
concerning the transfer of data to or from the client program via stream operations. It is 
passed as a parameter to each of the data transmission operations of the following sections 
to specify the stream to which the operations apply. 

A stream may be deleted by the operation: 

stream.Delete: procedure [sH:Stream. Handle]; 

The client must ensure that there are no outstanding references to the stream being 
deleted. Failure to observe this caution will result in unpredictable effects. 

3.2.1 GetBlock and PutBlock 

The principal operations for transferring blocks of data are Stream.GetBlock and 
Stream.PutBlock. Both are inline procedures. Each of these takes a parameter specifying 
the block of virtual memory to or from which bytes are to be transmitted. 

Stream. Block: TYPE = Environment.Block; 
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Environment. Block: TYPE = RECORD [ 

WockPointer: LONG POINTER TO PACKED ARRAY (0..0) OF Environment. Byte, 
startlndex, stopIndexPlusOne: cardinal]; 

A Block describes a section of memory which will be the source or sink of the bytes 
transmitted. The section of memory described is a sequence of bytes (not necessarily word 
aligned) which must lie entirely within a mapped space. blockPointer selects a word such 
that a startlndex of zero would select the left byte of that word (i.e., bits 0 - 7). The selected 
block consists of the bytes blockPointerft] for i in [startlndex..stopIndexPlusOne). Notice 
that a Block cannot describe more than 2 l *M bytes or 2 l5 -l words. A Stream. Block can 
describe any part of virtual memory. 

Some of the operations of this section and the next may cause signals to be generated. If 
such a signal is resumed, transmission continues from where it left off so that any changes 
made by the catch phrase to the Block record or to the input options (see below) are 
ignored. If, however, such a signal is RETRYed, the next byte of the stream sequence is 
transmitted to or from the byte specified by the current value of the Block record or input 
options, either of which might have been updated by the catch phrase. In no case is the 
stream sequence itself "backed up". Bytes previously received from input are not re¬ 
received, and bytes previously transmitted on output are not withdrawn. 

The primary block input operation is Stream. GetBlock. 

Stream. GetBlock: PROCEDURE [sH: Stream. Handle, block: Stream. Block] 
returns [bytesTransferred: cardinal, why: stream. CompletionCode, 
sst: stream.SubSequenceType]; 

stream.CompletionCode: type ■ {normal, endRecord, sstChange, endOfStream, 
attention, timeout}; 

The parameter block describes the virtual memory area into which the bytes will be 
placed. GetBlock does not return until the input is terminated. Its exact behavior, 
however, is controlled by a set of input options which may be set by the client using the 
following operation: 

Stream.SetlnputOptions: procedure [sH: stream.Handle, options: stream.InputOptions]; 
stream.InputOptions: type * record [ 

terminateOnEndRecord «— false, signalLongBlock«— false, signalShortBlock false, 
signalSSTChange false, signalEndOfStream 4- false, signalAttention 4- false, 
signalTimeout 4— TRUE,signalEndRecord: boolean 4—false]; 

Stream.defaultlnputOptions: Stream.InputOptions ■ []; 

SetlnputOptions controls exactly how GetBlock terminates and what signals it generates. 
Ordinarily (i.e., with the parameter options set to defaultlnputOptions) the transmission 
will not terminate until the entire block of bytes is filled unless there is a timeout. 
However, under the exceptional conditions described in §3.4, the" transmission may 
terminate before the block is filled and may also result in a signal. In all cases the 
procedure will return the actual number of bytes transferred, a CompletionCode 
indicating the reason for termination, and the latest SubSequenceType encountered. The 
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input operation may conveniently he restarted where it left off by first adding the result 
bytesTransferred to block.startlndex to update the record describing the block of bytes. 

In general, any status that may be returned from GetBlock may also be signalled, and the 
option to do so is available through InputOptions. A catch phrase for these signals must 
not attempt any other stream operations using the same Stream. Handle, for this will 
corrupt the internal state information maintained for the stream. 

Three circumstances which always suspend the transmission of data before the block is 
filled are the detection of a change in SubSequenceType, the detection of an attention, 
and the detection of the end of the stream. In the first case, if the input option 
signalSSTChange is false (the default) then the procedure GetBlock terminates 
immediately and returns the number of bytes transferred, with why = sstChange, and sst 
set to the new value of the SubSequenceType. If the input option signalSSTChange is true 
then the signal 

stream.SSTChange: signal [sst: stream.SubSequenceType, nextlndex: cardinal]; 

is generated. The parameter sst specifies the new SubSequenceType, and the parameter 
nextlndex specifies the byte index within the block where the first byte of the new 
subsequence will be placed. This signal may be resumed, and the effect is to continue the 
data transmission as though the change in SubSequenceType had not occurred (i.e., in the 
same block of bytes). 

If an attention is detected in the byte stream, the GetBlock terminates immediately and 
returns immediatly with the number of bytes transferred and with why = attention. If 
the input option signalAttention is true then the signal 

stream. Attention: signal [nextlndex: cardinal]; 

is generated. The parameter nextlndex specifies the byte index within the block where the 
position within the block where the next byte, the attention byte, would be placed. This 
signal may be resumed, and the effect is to continue the data transmission as though the 
Attention had not occurred (i.e., in the same block of bytes). 

A catch phrase for these signals must not attempt any other stream operations using the 
same Stream. Handle, for this will corrupt the internal state information maintained for the 
stream. 

Implementation of the end-of-stream feature is strictly transducer and filter specific, and 
optional. Transducer and filter implementors may implement an end-of-stream 
mechanism using any protocol they desire.When putting together a pipeline from a 
transducer and filters, great care needs to be taken to preserve the end-of-stream feature 
through all the stream components. If the input option signalEndOfStream is false (the 
default) and the stream component detects that the end-of-stream has occurred then the 
procedure GetBlock terminates immediately and returns the number of bytes transferred, 
with why = endOfStream. If the input option signalEndOfStream is true and the stream 
component detects that the end-of-stream has occurred then the signal 

stream.EndOfStrearn: signal [nextlndex: cardinal]; 
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is generated. The parameter nextlndex specifies the byte index immediately following the 
last byte of the stream sequence filled in a client’s block. 

Stream component implementors may provide special procedure calls in order to actively 
cause a stream to be terminated 

Semantics of the end-record feature are also transducer and filter specific. Furthermore, 
all transducers may not preserve the same semantics across the transmision medium. In 
any case, all notion of end-record processing may be suppressed by setting 
terminateOnEndRecord false (the default). If the input option terminateOnEndRecord is 
true and signalEndRecord is false (the default) and the stream component detects that the 
end-record has occurred then the procedure GetBlock terminates immediately and returns 
the number of bytes transferred, with why = endRecord If the input option 
signalEndRecord is TRUE and the stream component detects that the end-record has 
occurred then the signal 

stream. EndRecord: signal [nextlndex: cardinal]; 

is generated. The parameter nextlndex specifies the byte index immediately following the 
last byte of the stream sequence filled in a client’s block. 

The principal block output operation is Stream.PutBlock. 

Stream. PutBlock: PROCEDURE [sH: Stream. Handle, block: Stream. Block, 
endRecord: boolean «-false]; 

This operation is analogous to Stream. GetBlock. The parameter block describes the area of 
virtual memory from which information is transmitted. This procedure returns only after 
the data has been accepted by the stream, at which time the client may reuse block. If the 
client is ignoring record boundaries (the default), endRecord should be set to false. 
Otherwise, see the section on controlling physical record characteristics, §3.4. 

Stream operations have the right to discard empty blocks, hence a PutBlock operation 
specifying a block of length zero may be a no-op even if endRecord is true. 


3.2.2 Additional data transmission operations 

In addition to GetBlock and PutBlock, the following operations are provided to permit the 
sending and receiving of individual bytes, characters and words. All but SendNow are 
inline procedures. They are supplied so that some streams can provide byte or character or 
word operations in a more efficient manner than is possible with GetBlock or PutBlock. 
The documentation for individual streams should be consulted for detailed performance 
information. 

Stream.GetByte: PROCEDURE [sH: Stream.Handle] RETURNS [byte: stream.Byte]; 
stream.GetChar: procedure [sH: stream.Handle] returns [char: character]; 
stream.GetWord: procedure [sH: stream.Handle] returns [word: stream.Word]; 

Stream.Word: TYPE = Environment. Word; 
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GetByte and GetChar operations get the next Byte or character from the stream sequence 
and return it just as a call upon Stream. GetBlock specifying a Block containing one byte 
- would. The GetWord operation gets the next Word from the stream sequence and returns 
it just as a call upon GetBlock specifying a Block containing Environment. bytesPerWord 
bytes would. In all three cases, the effect is as if the input options to GetBlock had been 
signalShortBlock, signallongBlock, signal Attention, signal EndRecord and 
terminateOnEndRecord = false, and signalEndOfStream, signalTimeout and 
signalSSTChange = true. Thus, these operations may result in the signal SSTChange, 
EndOfStream or stream.TimeOut (see §3.2.4). 

Note: When any of the signals are generated when processing a GetWord and nextlndex 
is an odd value, the two communicating processes are responsible for the outcome. 

stream. PutByte: procedure [sH: stream. Handle, byte: Stream. Byte]; 

stream.PutChar: procedure [sH: stream.Handle, char: character]; 

Stream.PutWord: procedure [sH: stream.Handle, word: Stream.Word]; 

stream.PutString: procedure [sH: stream.Handle, string: long string, endRecord «- false]; 

The PutByte and PutChar operations transmit the Byte or character to the medium just as 
a call on Stream. PutBlock specifying a Block containing one byte would. The PutWord 
operation transmits the next Word to the medium just as a call on PutBlock specifying a 
Block containing Environment.bytesPerWord bytes would. In the first three cases, the effect 
is as if endRecord is set to false in the call to PutBlock. PutString transmits the bytes 
described by string to the medium. 

stream.SendNow: procedure [sH: stream.Handle, endRecord*- false]; 

This operation flushes the stream sequence. It guarantees that all information previously 
output (by means of PutBlock, PutByte, PutChar, PutWord, PutString, or SetSST) will 
actually be transmitted to the medium (perhaps asynchronously). The default 
implementation of this procedure is equivalent to a call on Stream. PutBlock specifying a 
Block containing no bytes and endRecord set to TRUE (see §3.4). Client programs should 
call SendNow at appropriate times to ensure that the bytes and changes in 
SubSequenceType have actually been sent and are not buffered internally within the 
stream, awaiting additional output operations. 

Through use of the endRecord parameter, SendNow may apply transducer or filter 
specific semantics to the transmission of the data, such as the idea of a logical record . A 
logical record may be a collection of one or more physical records. The logical record 
boundaries can be detected by the receiving client by proper setting of 
terminateOnEndOfRecord and perhaps signalEndRecord in the streams's InputOptions. 

3.2.3 Subsequence types 

The subsequence type of a stream may be changed by 

stream. SetSST: procedure [sH: stream. Handle, sst: stream. SubSequenceType]; 
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All subsequent bytes transmitted on the stream have the indicated SubSequenceType. 
Even if the subsequent sequence of bytes is null (i.e., a call on SetSST is immediately 
followed by another), the SubSequenceType change demanded by this call will still be 
available to the receiver of the stream sequence. 

SubSequenceTypes are intended to be used to delineate different kinds of information 
flowing over the same stream (e.g., to identify control information, indicate end-of-file, 
etc.). The interpretation of a SubSequenceType value is a function of the particular 
stream. 

A SetSST operation specifying a SubSequenceType identical to the previous 
SubSequenceType is a no-op. Otherwise, SetSST always has the side effect of completing 
the current physical record, as explained in §3.4. 

3.2.4 Attention flags 

The following operation causes an attention flag and an associated byte of data to be 
transmitted via the stream facility. 

stream.SendAttention: procedure [sH: stream.Handle, byte: stream.Byte]; 

Note that the attention flag and the data byte occupy a byte in the stream sequence. The 
attention is sent as both an in-band and out-of-band signal The out-of-band attention is 
not necessarily transmitted in sequence, but may bypass bytes and changes in 
SubSequenceType which were transmitted before it. byte is used by the client protocol to 
transmit other information regarding this attention. 

The following operation awaits the arrival of an attention flag. 

stream. WaitForAttention: procedure [sH: stream.Handle] returns [stream. Byte]; 

When the out-of-band attention is received on stream sH, this procedure returns the byte 
of data associated with the attention. It is the responsibility of the client program to 
determine the appropriate action to take. If more than one attention flag has been sent, 
these will be queued by the stream. Each return from a call on WaitForAttention 
corresponds to precisely one attention sent by SendAttention. 

When the in-band attention is received on stream sH, the effect depends upon the setting 
of the InputOptions. If signalAttention is false, the operation terminates with a 
completion code of attention. The next byte in the stream is the byte passed to 
SendAttention. If the input options specify signalAttention as true, the signal Attention 
is raised with the index pointing in the current block to the byte passed to SendAttention. 

WaitForAttention is usually executed by a different process from that operating upon the 
stream. It returns as soon as the attention is received, whether or not all of the bytes 
preceeding it in the stream have been transferred. 
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3.2.5 Timeouts 

Any of the operations of this section (except Send Attention and WaitFor Attention) may 
fail to complete within a reasonable amount of time due to external conditions. In such a 
case the following signal is generated: 

Stream.TimeOut: signal [nextlndex: cardinal]; 

The parameter of this signal indicates the position within the block of bytes where the 
next byte would be placed. This signal may be resumed. 

If this signal is RETRYed all previously received data may be lost. This is because it is likely 
that a stream component is performing internal buffering (transferring data from its 
buffer into the client’s block), and the action of RETRYing the signal may not tell the 
component that it must refill the client's block. Even if the component was informed of this 
fact, it may have discarded data already transferred into the client's block from its 
internal buffer. 

A catch phrase for this signal must not attempt any other stream operations using the 
same Stream. Handle, for this will corrupt the internal state information maintained for the 
stream. 

The timeout value for the stream may be read and altered by using the getTimeout and 
setTimeout procedures in the Stream. Object (section 3.5.1). 

msecs sH.getTimeoutfsH]; 

sH.setTimeoutfsH, msecs]; 

3.2.6 Stream positioning 

For those streams which may be accessed randomly, the position of a stream may be 
determined with the procedure 

Stream. GetPosition: procedure [sH: Stream. Handle] 
returns [position: stream. Position]; 

Stream. Position: TYPE = LONG CARDINAL; 

The value returned is the byte index of the next byte to be read from or written in the file. 

The position of a stream may be set with the procedure 

stream.SetPosition: procedure [sH: Stream.Handle, position: stream.Position]; 

3.3 Creating streams 

Pilot provides no general operations for creating streams. The main reason for this is that 
the components of a stream (pipelines, transducers, and filters) must be able to take 
arbitrary parameters at the time they are created. It is not possible for Pilot to specify a 
general interface for their creation without either compromising the basic type-safeness of 
Mesa or constraining the flexibility and power of client-provided streams. Thus, the create 
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function is implemented on a ease by-ease basis, and clients must therefore refer to 
documentation for individual stream components for the correct interface for this 
operation. Specifications for Pilot-provided transducers and filters are included in § 3.6. In 
this section, the general style is illustrated by means of hypothetical examples. 

For example, if a utility package implements a transducer to a magnetic cassette reader, it 
is obligated to provide a means by which other clients can create instances of that 
transducer, use them, and later delete them. Suppose the name of the interface module 
providing this function is CassetteStream . Then it would provide the following operation: 

Cassettes tream.Cre ate: procedure [ —optional parameters — ] 
returns [stream. Handle, — optional other results —]; 

A client wishing to use the stream interface to access this device would thus call 
CassetteStream.Creaie , then use the Stream. Handle returned from it as parameter to the 
stream operations of this chapter. When the stream was no longer needed, it would be 
deleted by calling Stream. Delete. 

Similarly, a security package providing, say, an encryption facility might implement this 
by means of a filter for a stream. In this case, the interface module might be called 
EncryptionFilter , and it would provide the following operation: 

EncryptionFilter. Create: procedure [stream. Handle, —optional other parameters —] 
returns [stream. Handle, — optional other results —]; 

The client could easily couple an instance of this filter with the transducer above. This is 
done by calling EncryptionFilter.Create, passing as a parameter the Stream. Handle returned 
from CassetteStream.Creaie . Then the Stream. Handle returned from EncryptionFilter. Create 
would be the one used in GetBlock, PutBlock, and the other operations of §3.2. The net 
effect would be stream components which, on input, read bytes from the cassette reader, 
decrypt them, and pass them to the client and which, on output, encrypt the bytes supplied 
by the client and write them on the cassette. 

In general, a procedure creating a filter accepts one Stream. Handle as a parameter and 
returns another as its result. Thus, several filters, each implementing a simple 
transformation, may be concatenated together to implement a more interesting 
transformation on the stream sequence. The parameter passed to each one is the result 
returned from the adjacent one. Such a concatenation, called a pipeline , is illustrated in 
Figure 3.3a. 



Figure 3.3a 
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This diagram illustrates how each Stream. Handle returned from a transducer or filter is 
passed as a parameter to the next adjacent filter, and how the last one is used directly by 
the client. In particular, />f is returned from the procedure which creates Transducer It is 
passed to the procedure which creates Filter B , returning This is passed, in turn, to the 
next filter, and so on, until h n is returned and passed to Filter A. Filter A is the last one in 
the pipeline, and its Stream. Handle, /), is returned to the client. 

Figure 3.3b shows the flow of data through the pipeline and the use of the various 
Stream. Handles as a result of a client call on Stream. GetBlock (calls on other data 
transmission operations are analogous). 


GetBlockfh,...] 

GetBlock[h n ,...] 


GetBlock[hi,...] 


device operation 



^ hn _ 




Client 

Filter A 


Filters 


Transducer 


Figure 3.3b 


Here, the client calls Stream. GetBlockfh, ... ], which is transformed by the stream interface 
into an appropriate call on Filter A. Filter A, in turn, calls stream. GetBlock[h n , . • - which is 
passed to the next filter in the pipeline, and so on, until eventually a call is made on 
Stream. GetBlock[/i 2 , . . . ]. This is transformed into a call on Filter £?, which then calls 
Stream. GetBlock[/if ff ... ], to invoke Transducer , which actually operates the device. 

Note that the only difference between a transducer and a filter is that a transducer 
interfaces to some device or channel, while a filter interfaces to another stream and, thus, 
indirectly to another filter or transducer. 

Note also that the client can construct a pipeline "manually," by tediously assembling the 
various components, instantiating each of them, and binding them together. However, a 
pipeline can also be presented as an integrated package, already assembled. For example, 
the two components described above may have been assembled into a pipeline called 
EncryptingCassetteStream. This pipeline might then provide the following operation, 
which clients can call to create an procedure an instance of this pipeline: 

EncryptingCassetteStream. Create : procedure [ — optional parameters — ] 
returns [stream. Handle, —optional other results — J; 

The client of such a stream would merely invoke this procedure to create the stream 
without having to bother about finding and putting together the individual components. 

3.4 Control over physical record characteristics 

Most of the time, the client will not wish to know about how the data in a stream sequence 
is divided into physical records for recording or transmission. For some applications, 
however, this is of vital importance. The stream facility has been designed so that the 
details of the physical encoding can be ignored when desired, or completely known and 
controlled when that is necessary. On output, complete control of the placement of bytes in 
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physical records can be achieved for most media. On input, complete information is 
available about how the bytes were arranged in physical records. 

These facilities to control the placement of bytes on physical records are not meant to be 
used as a means of transmitting information. In particular, a transducer might suppress 
or generate empty physical records and will necessarily partition oversize "physical" 
records into smaller ones. Any filter may rearrange (or completely obliterate) physical 
record boundaries. Documentation for the individual transducer or filter and for the 
individual transmission or storage medium should be consulted for full details. 

The output and input cases will be treated separately. On output, bytes will be placed in 
turn into the same physical record until one of the following events occurs: 

1. The SendNow procedure is called. It has the side effect of causing the current record to 
be sent. The next byte output will begin a new physical record. This is the main 
mechanism for controlling physical record size on output. 

A SendNow with endRecord true may apply further transducer or filter dependent 
semantics, such as end of logical record. 

2. A PutBlock procedure is called with an endRecord parameter of TRUE (this is equivalent 
to a SendNow with endRecord true). After the transmission of this block of bytes, the 
current physical record is ended. If, at this point, the physical record is at its 
maximum size (see 5. below), an empty record will not be transferred. 

3. A SetSST procedure has been called. The first byte of a new subsequence always begins 
a new record and has the new SubSequenceType. This may cause the previous record 
to be sent. 

4. Enough bytes have been output to fill the physically maximal record. At this point the 
record will be written and a new record started. This maximum number is a function 
of the medium being written, hence documentation concerning the medium must be 
consulted to determine this value. 

5. Some other device-dependent event, such as a timeout, occurs. In this case, a buffer 
may be flushed automatically. Details are documented with individual transducers. 

On input, bytes will be placed in turn into the record until one of the following events 
occurs: 

1. The end of the logical record is reached, and the input option terminateOnEndRecord 
is true. 

The end of the logical record is reached at the same time that the block of bytes 
described in the Block record is exhausted. In this case, neither of the signals 
ShortBlock and LongBlock is generated. If the input option terminateOnEndRecord is 
true, then why is set to endRecord; otherwise, it is set to normal. 

In any case, if the input option signalEndRecord is true and the logical record has just 
been exhausted, then the following signal is generated. 

stream.EndRecord: siGNAL[nextindex: cardinal]; 


3-12 




Pilot Programmer’s Manual 


3 


This signal indicates by nextlndex the position within the block of bytes where the 
next byte will be placed. If it is resumed, transmission continues as if it had not been 
generated. 

A catch phrase for this signal must not attempt any other stream operations using the 
same Stream.Handle, for this will corrupt the internal state information maintained for 
the stream. 

2. The end of a physical record is reached, the block of bytes described in the Block record 
is not exhausted, and signalLongBlock is true. 

If signalLongBlock is true, the following signal is generated: 

stream.LongBlock: signal [nextlndex: cardinal]; 

This signal indicates by nextlndex the position within the block of bytes where the 
next byte will be placed. If it is resumed, transmission continues as if it had not been 
generated. 

A catch phrase for this signal must not attempt any other stream operations using the 
same Stream.Handle, for this will corrupt the internal state information maintained for 
the stream. 

3. The block of bytes described in the Block record is exhausted, the end of the physical 
record has not been reached, and the input option signalShortBlock has the value true. 
At this time the input is terminated (without losing the subsequent bytes of the 
physical record, which are still available for reading by subsequent GetBlock 
operations), and the signal Stream. ShortBlock is generated. 

Stream.ShortBlock: error; 

This signal may not be resumed. 

The easiest approach is usually to establish a Block longer than the longest expected 
physical record and specify input options signalLongBlock as false, signalShortBlock as 
true, and terminateOnEndRecord as true. At this point the transmission will cease with 
the entire contents of the physical record in the block of bytes, and the number of bytes 
transmitted will be returned as the result of the GetBlock procedure. In this way a signal 
will be generated only under unusual circumstances. 

3.5 Transducers, filters, and pipelines 

The stream package is designed so that clients can implement their own stream 
components (transducers, filters, and pipelines). The implementor of one of these has three 
different obligations to fulfill. First, he must design an interface (i.e.. Mesa definitions 
module) in the style described in the section about creating streams, §3.3, by which his 
clients create instances of that stream component. Such an interface (together with its 
accompanying implementation modules) is called a stream component manager. Second, 
he must provide a functional specification describing this interface and the detailed 
behavior of the stream component, including any specific signals, errors, parameters, etc., 
which it defines. Third, he must implement the actual component, if it is a filter or 
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transducer. (Pipelines are assumed to be composed of previously implemented components 
which already have their own component managers and documentation.) 

This section describes the standards, data types, and operations to be used in defining a 
new stream component It discusses, the precise interface which each instance of each 
filter or transducer must provide, and outlines a typical method for implementing a filter 
or transducer manager 


3*5d Representing filters and transducers 

At run time, a filter or transducer is represented by sixteen procedures, a set of options 
and an instance data field so that clients may associate other data with a stream instance. 
The procedures execute in a common context to provide the data transmission operations 
of that filter or transducer. Descriptors for these procedures are stored in a record defined 
by the stream package, and pointed to by a Stream. Handle. 

The procedures stored in Object must implement the semantics of the corresponding 
procedures (GetByte, Put, etc.) described in §3.2 on the stream sH. In particular, they must 
terminate according to the specifications of those sections and must generate the 
appropriate signals (SSTChange, LongBlock, ShortBlock, EndOfStream, TimeOut, 
EndRecord) as required 

Stream. Handle: TYPE = LONG POINTER TO Stream. Object; 

Stream.Object: TYPE SS RECORD [ 
options: Stream.InputOptions, 
getByte: stream GetByteProcedure, 
putByte stream.PutByteProcedure, 
getWord: stream GetWordProcedure, 
putWord: Stream PutWordProcedure, 
get: Stream.GetProcedure, 
put: Stream.PutProcedure, 
sets ST: stream.SetSSTProcedure, 
sendAttention: stream.SendAttentionProcedure, 
waitAttention: stream WaitAttentionProcedure, 
delete: stream.DeleteProcedure 
getPosition: stream.GetPositionProcedure 
setPosition: stream.SetPositionProcedure 
sendNow: stream.SendNowProcedure, 
clientData: long pointer, 
getSST: stream.GetSSTProcedure, 
getTimeout: stream.GetTimeoutProcedure, 
setTimeout: stream.SetTimeoutProcedure]; 

A client call on a Pilot stream operation is normally converted by the stream package into 
a call on the appropriate procedure named in the Stream. Object pointed to by the 
Stream. Handle parameter of that operation. Thus, it is the responsibility of the 
implementor of each filter and transducer to satisfy exactly the specifications of the 
stream package Pilot assists in this task by utilizing the Mesa type checking machinery 
and by defining the uniform interface encapsulated by Stream. Object. 
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In this section, the meanings of the fields of Stream. Object are enumerated and a default 
Stream.Object described. 

The options field specifies the currently valid input options for the stream. 

options: Stream.InputOptions; 

This field is set by Stream. SetlnputOptions and its current value is passed as a parameter 
to the get procedure described below. Implementors of filters and transducers need not be 
concerned with maintaining or inspecting this field. 

The get field specifies the block input procedure of the stream. 

get: stream. GetProcedure; 

stream. GetProcedure: type ■ 

procedure [sH: stream.Handle, block: stream.Block,options: Stream.InputOptions] 
returns [bytesTransferred: cardin AL,why: stream.CompletionCode, 
sst: stream.SubSequenceType]; 

In a filter, the body of a GetProcedure will typically contain one or more calls on GetBlock, 
GetByte, GetChar, or GetWord with a Stream.Handle parameter pointing to the next 
stream component in the pipeline (i.e., the parameter passed at the time this filter was 
created). In a transducer, the body of a GetProcedure will typically have calls on input 
operations for the specific device being supported. 

The getByte field specifies the byte input procedure of the stream. 

getByte: stream.GetByteProced ure; 

stream.GetByteProcedure: type = procedure [sH: stream.Handle] 
returns [byte: stream.Byte]; 

The getWord procedure specifies the word input procedure of the stream. 
getWord: stream. GetWordProcedure; 

stream.GetWordProcedure: type = procedure [sH: stream.Handle] 

RETURNS[word : Stream. Word]; 

The put field specifies the block output procedure provided by the filter or transducer. 

put: stream.PutProcedure; 
stream.PutProcedure: type = 

procedure [sH: stream.Handle, block: stream.Block, endRecord: boolean]; 

This procedure must regard the parameter endRecord * true as an indication to flush any 
output buffers and actually initiate the physical transmission of information. It may 
suppress output requests specifying a block of no bytes provided that there is no previous 
output, change in SubSequenceType, or attention flag still waiting to be sent. This 
procedure may generate the signal TimeOut if necessary. 
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In a filter, the body of a PutProcedure will typically contain one or more calls on PutBlock, 
PutByte, PutChar, PutWord, or SendNow with a Stream. Handle parameter pointing to the 
next stream component in the pipeline (i.e., the parameter passed at the time this filter 
was created). In a transducer, the body of a PutProcedure will typically have calls on 
output operations for the specific device being supported. 

The putByte field specifies the byte output procedure provided by the transducer or filter. 

putByte: stream.Pu tByteProced u re; 

stream.PutByteProcedure » procedure [sH: stream.Handle, byte:stream.Byte]; 

This procedure may generate the signal TimeOut if necessary. 

The putWord field specifies the word output procedure provided by the transducer or 
filter. 

putWord: stream.PutWordProcedure; 

stream.PutWordProcedure » procedure [sH: stream.Handle, word: stream. Word]; 

This procedure may generate the signal TimeOut if necessary. 

The setSST field specifies the procedure to change the current SubSequenceType of the 
output side of the filter or transducer. 

setSST: stream. SetsSTProcedure; 

stream.SetSSTProcedure: type ■ procedure [sH: stream.Handle, 
sst: stream.SubSequenceType]; 

This procedure should be a no-op if the new SubSequenceType of sH is the same as the old 
one. Otherwise, it should have the effect of completing the current physical record (as if a 
call on Stream. SendNow had been made immediately before). 

A call on setSST may have the effect of changing the internal state of the stream 
component, or in the case of a filter, it may result in a call to SetSST to the next stream 
component in the pipeline, or both. 

The getSST field specifies the procedure to find the current SubSequenceType of the 
output side of the filter or transducer (the SST set by SetSST). The input SST can be found 
by doing a get of 0 bytes. 

getSST: stream.GetSSTProcedure; 

stream. Gets STProcedure: type * procedure [sH: stream.Handle] 
returns [sst: stream.SubSequenceType]; 

The sendAttention and waitAttention fields specify the two procedures implementing the 
sending of and waiting for attention flags in the transducer or filter. 

sendAttention: stream.SendAttentionProcedure; 
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waitAttention: stream. WaitAttentionProcedure; 

Stream.SendAttentionProcedure: type a procedure [sH: stream.Handle, 
byte: stream.Byte]; 

stream. WaitAttentionProcedure: type a procedure [sH: stream. Handle] 
returns [byte: stream.Byte]; 

These two procedures will be called by stream.SendAttention and stream.WaitForAttention, 
respectively. 

The getTimeout field specifies the procedure to find the current timeout field of the filter 
or transducer. 

getTimeout: Stream.GetTimeoutProcedure; 

stream.GetTimeoutProcedure: type a procedure [sH:stream.Handle] 
returns [waitTime:LONG cardinal - msecs-]; 

The setTimeout field specifies the procedure to set the current timeout field of the filter or 
transducer. 

setTimeout: stream.SetTirneoutProcedure; 

stream.SetTimeoutProcedure: type a procedure [sH:stream.Handle, 
waitTime:LONG cardinal - msecs- ]; 

The delete field specifies a procedure implementing the deletion of a filter or transducer. 

delete: stream. Del eteProcedu re; 

stream. DeleteProcedure: type a procedure [sH: stream. Handle]; 

This procedure is called by the Stream.Delete operation. 

The getPosition and setPosition fields specify procedures implementing the setting and 
recovering of a stream position. 

getPosition: stream.GetPositionProcedure; 

stream.GetPositionProcedure: type a procedure [sH: stream.Handle] 
returns [position: stream.Position]; 

setPosition: stream.SetPositionProcedure; 

stream.SetPositionProcedure: type a procedure [sH: stream.Handle, 
position: stream.Position]; 

The sendNow field specifies a procedure to force data to be transmitted. 

sendNow: stream.SendNowProcedure; 
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stream. SendNowProcedure: type s procedure [sH: stream. Handle, 
endRecord: boolean false]; 

This procedure is called by the Stream. SendNow operation. 

The following object is provided to supply default values for a Stream. Object. It is an 
exported variable. The implementor of a stream can use it to ease the burden of 
initializing all of the fields in a Stream. Object although the implementor must still 
initialize some of the fields. 

Stream.defaultObject: READONLY Stream.Object a [ 
options: stream.defaultlnputOptions, 
get Byte:..— requires sH.get to be defined 
putByte:..— requires sH.put to be defined 

getWord:...,— requires either sH. getByte or sH.get to be defined 
putWord:...,— requires either sH.putByte or sH.put to be defined 
get: ..., — requires sH . getByte to be defined 
put:...,— requires sH.putByte to be defined 
setSST, sendAttention, waitAttention, delete:..., ] 

In this description, the phrase "to be defined" means that the supplied default procedure 
assumes that the user has supplied the indicated procedure as opposed to using the default 
procedure. Thus, the implementor of the stream must supply either getByte or get - both 
cannot be defaulted. Similarly, the implementor must supply either putByte or put - both 
cannot be defaulted. The default entries for setSST, getSST, setTimeout, getTimeout 
sendAttention, waitAttention and delete simply raise the exception 
Stream.InvalidOperation. Thus, the implementor must supply these procedures. 

stream.lnvalidOperation: error; 

Individual default procedures may be extracted for client use by the standard Mesa 
extractor expression. For example, the default get procedure is defaultObject.get. 

Caution: The effect of not providing at least one of getByte/get (putByte/put) is 
unspecified by Pilot. Thus the stream implementor must be sure to provide at least one of 
each of these pairs of procedures. 


3.5.2 Stream component managers 

Implementors of stream components may create instances of them by whatever means is 
most appropriate to their requirements. A particular filter or transducer may, for 
example, consist of one module, a collection of modules, a local frame used in conjunction 
with the Mesa PORT facility, or some other construct. Moreover, it may be allowed to exist 
on a given machine in only one or a limited number of copies which are regarded as 
"serially reusable" resources (for example, a transducer to a particular device, of which 
there is only one or a limited number on a machine), or it may be allowed to exist in as 
many copies as appropriate (for example, the Network stream of §6.3). It is the 
responsibility of the stream component manager to create (or control access to) instances 
of that stream component, as appropriate. When access is granted, the component 
manager must also provide a pointer to a Stream.Object containing procedure descriptors 
for that component. 


3-18 




Riot Programmer’s Manual 


3 


One way of implementing a component is as a single module which is instantiated at run¬ 
time by the Mesa new statement Declared within this module would be the procedures of 
the component plus a Stream. Object which would contain their procedure descriptors. The 
component manager executes new to create a new instance of one of these, followed by 
START to initialize it, pass any parameters to it, and get back a pointer to the Stream. Object. 

The component manager deletes instances of stream components by calling 

Runtime. UnNew or Runtime. SelfDestruct. 

Runtime. SelfDestruct sets the internal state of the process so that the module in which the 
calling procedure is declared will be un-NEW'd after the calling procedure returns to its 
own caller. This operation has the effect of placing a "self-destruct" mechanism in the 
module which will take effect after the calling process exits from it. Thus, it is a means of 
deleting the stream component from within that component. . 

The typical use of Runtime. Self Destruct will be from a procedure named in the delete entry 
of the Stream. Object. The component manager will call h.deletefh] (where h is a 
Stream. Handle). This procedure will perform the necessary finalization, such as flushing 
buffers, closing files or connections, releasing storage and resources, etc. It will then call 
Runtime. SelfDestruct and finally return to the component manager. After this return, the 
module representing this instance of the stream component will be automatically deleted 
and space occupied by the component's global frame freed. 

Caution: The client must ensure that there are no outstanding references to the 
component module being deleted - i.e., no procedure descriptors or pointers which might 
be used. In addition, any process waiting for attentions (i.e., a process which has called but 
not returned from WaitForAttention) must be aborted and allowed to exit from the 
module. Failure to observe this caution will result in unpredictable effects. In particular, 
Runtime.UnNew must be called from outside the module being deleted. 
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A file is the basic unit of long-term information storage (see §4.3). A file consists of a 
sequence of pages, the contents of which can be preserved across system restarts. Files are 
stored on volumes (see §4.1, 4.2) and are identified by the containing volume and a file 
identifier which is unique within that volume. 

Pilot stores files on logical volumes , which are contained in physical volumes of storage 
devices (typically disks). A physical volume is the basic unit of physical availability for 
random access file storage. It represents the notion of a storage medium whose 
availability is intrinsically independent of that of other instances of such media (e g., one 
physical disk pack). A logical volume is either a physical volume or a subset of a physical 
volume or a collection of subsets of physical volumes. A logical volume is the unit of 
storage for client files and the system data structures for manipulating them. It becomes 
logically available or unavailable as a unit and contains only complete files (i.e ., files 
cannot span logical volumes). Volumes which have been damaged may be restored by 
scavenging (see §4.4). 

Client programs access data in files by mapping them into spaces in virtual memory (see 
§4.5). Pilot provides client programs with facilities for associating areas of virtual 
memory with portions of files, for allocating sections of virtual memory independent of. 
mapping, and for influencing swapping between virtual and real memory. 

Pilot provides free storage management through zones and heaps (see §4.6). Zones are 
segments of storage in client-designated areas of virtual memory. Heaps are available for 
managing arbitrarily sized nodes; they support the Mesa language facilities for dynamic 
storage allocation. 

A general purpose log file facility (§4.7) allows recording of information in a client- 
supplied log file. 

4.1 Physical volumes 

Physical Volume: definitions ..; 

This section describes those interfaces provided by Pilot which permit clients to initialize 
and manage physical volumes Pilot brings the system physical volume online during 
Pilot initialization, repairing it if necessary. Thus most clients will not need to use the 
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facilities in this section. However. Utility Pilot-based clients do not have a system 
physical volume, these clients must manage physical volumes themselves. Clients which 
might use the PhysicalVolume facilities include volume management utility programs, 
system elements with several physical volumes, and UtilityPilot-based systems. Sections 
4.1.1 through 4.1.4, 4.1.7, and 4.1 8 deal with general physical volume management, 
section 4.1.5 with initializing a physical volume, and section 4.1.6 with scavenging. See 
also Chapter 8 for facilities to format physical volumes and install boot files on them. 


4.L1 Physical volume name a.id size 

The fundamental name for a physical volume is its ID. 

PhysicalVolume.lD: TYPE = System.PhysicalVolumelD; 

System.PhysicalVolumelD: type * record [system.UniversallD]; 

PhysicalVolume. nulllD*. PhysicalVolume. ID x [System. nuillD); — "null ID" 

Pilot ensures with a very high probability that each distinct physical volume is assigned a 
distinct ID. No ID is reused for any purpose by any copy of Pilot on any machine at any 
time. Thus, a physical volume may be unambiguously identified by its ID, even if it is 
moved to another machine or environment, or if it is stored off-line for a long time. nulllD 
is never assigned as an ID and is used to indicate the absence of a physical volume. 

The error PhysicalVolume. ErrorfphysicalVotumeUnknown] may be raised by any of the 
operations that take an ID as an argument. 

A physical volume is organized as a sequence of up to 2 32 pages, each containing 
Environment. wordsPerPage words. Pages are numbered starting from zero. The actual 
volume size is accounted for by Pilot and does not result in the redefinition of the 
maximum page number. 

Physicaivolume.PageCount: type x long cardinal; 

PhysicalVolume. firstPageCount: Physicaivolume.PageCount = 0; 

PhysicalVolume. lastPageCount: Physicaivolume.PageCount X LASTILONG cardinal]; 

PhysicalVolume. PageNumber: type ■ long cardinal; 

Physicaivolume.firstPageNumber: PhysicaiVolume.PageNumber = 0; 

PhysicalVolume. lastPageNumber: PhysicaiVolume.PageNumber = last[long cardinal] 1 ; 

Pilot's maximum values for PageCount and PageNumber do not, for all practical purposes, 
limit the size of a physical volume. 


4.1.2 Physical volume errors 

PhysicalVolume operations may raise the following signals: 
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PhysicalVolume. Error: ERROR [error: PhysicalVolume.ErrorType 1; 

PhysicalVolume.ErrorType: type * {badDisk, badSpotTableFull, containsQpenVolumes, 
diskReadError, hardwareError, hasPilotVolume, alreadyAsserted, insufficientSpace, 
invalidHandle, nameRequired, notReady, noSuchDrive, noSuchLogicalVolume, 
physicalVolumeUnknown, writeProtected, wrongFormat, needsConversion}; 

PhysicalVolume. NeedsSca venging : error; 

The conditions causing each error are described as the error occurs in the text. The errors 
raised by each operation are indicated with the operation’s description. 

4.1.3 Drives and disks 

A drive is an I/O device capable of containing a Pilot physical volume. Such devices have a 
Oevice.Type which is in the range defined by Device.PilotDisk. The storage medium on a 
drive is the physical object which holds the stored information, typically a fixed disk or a 
removable disk pack. It will be called a disk in the description which follows. A drive is 
uniquely named by its device index. A drive may be in two states : if a drive is ready then it 
contains a storage device, e.g., a disk pack, that may be accessed by Pilot; if the drive is not 
ready then it does not contain an accessible storage device. 

PhysicalVolume.ErrorType: type » {..., noSuchDrive,.. .}; 

All operations which take a device index will raise PhysicalVolume. Error[noSuchDrive] if 
provided a device index which does not denote a drive. 

The set of drives on a machine may be enumerated with the operation 

PhysicalVolume. GetNextDrive: procedure [index: cardinal] returns [nextlndex: cardinal]; 

Physicalvoiume.nullDevicelndex: cardinal = last[cardinal]; 

GetNextDrive is a stateless enumerator. Enumeration begins and ends with the value 

nullDevicelndex. GetNextDrive may raise Error[noSuchDrive] . 

For every drive, Pilot maintains a monotonically increasing change count of the number of 
times that the drive has changed state between ready and not ready. If a drive changes 
state, the change count for that drive will increase by at least one. Thus while the change 
count remains the same the client can be sure that the same disk is mounted on the drive. 

The client may wait for one or more drives to change state by invoking 

Physicalvolume.AwaitStateChange: procedure [changeCount: cardinal, 
index: cardinal «- Physicalvoiume.nullDevicelndex] 
returns [currentChangeCount: cardinal]; 

The AwaitStateChange operation waits until the change count of the drive equals or 
exceeds changeCount, then returns the new change count. If index a nullDevicelndex, 
the operations waits until the sum of the change counts of all drives equals or exceeds 
changeCount, then returns the sum AwaitStateChange may raise ErrorfnoSuchDrive] 
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A unique instance of a disk mounted on a drive is represented bv a PhysicalVolume. Handle 
A Handle denotes both a drive and the change count at the time at which the Handle was 
obtained. A Handle is valid until the drive that it denote^ changes state. After that time, 
the error ErrorfinvalidHandle] is raised by any operation that takes a Handle as an 
argument. 

PhysicalVolume. Handle: type [31; 

PhysicalVolume. ErrorType: type = {. .., invalidHandle,.. 

PhysicalVolume. GetHandle: PROCEDURE [index: CARDINAL] RETURNS [PhysicalVolume. Handle]; 

Physicaivolume.InterpretHandle: procedure [instance: PhysicalVolume. Handle] 
returns [type: Device.Type, index: cardinal]; 

A Handle is obtained for a drive using GetHandle. The change count of the drive at the 
time GetHandle is invoked defines the valid change count for the disk mounted on the 
drive represented by the returned Handle. GetHandle may raise Error[noSuchDrive]. 
InterpretHandle returns the drive denoted by a given Handle. The returned type may be 
general rather than precise, i.e., a type naming a device family rather than a specific 
member of the family. InterpretHandle may raise ErrorfinvalidHandle]. 

Information about the ready state of a drive can be obtained with 

PhysicalVolume. IsReady : PROCEDURE [instance: PhysicalVolume.Handle] 
returns [ready: boolean]; 

IsReady may raise ErrorfinvalidHandle]. 

4*1.4 Disk access. Pilot volumes, and non-Pilot volumes 

The disk on a ready drive may be in one of three states: inactive, Pilot access, and non- 
Pilot access. An inactive disk may be accessed only in stylized ways that permit clients to 
determine in which of the other two states to place the device. A disk with Pilot access 
contains a Pilot physical volume and may be accessed only through the Pilot File, 
PhysicalVolume, Space and Volume interfaces. Non-Pilot access indicates that the the disk may 
be accessed only through special interfaces which permit direct access (that is, 
unembellished with Pilot space, mapping and file structures) to the storage device. 
Whenever a drive becomes ready, Pilot places its disk in the inactive state. Once a client 
has obtained a Handle for a drive and ascertained that the disk is ready, the client must 
inform Pilot what type of access to the disk is desired. The following operations allow 
clients to determine and change the state of a drive. 

To aid the client in determining how to access a disk, Pilot provides two facilities. The 
first is an operation which examines the disk and determines whether or not it contains a 
Pilot volume. 

PhysicalVolume. GetHints: PROCEDURE [ 

instance: PhysicalVolume.Handle, label: long string nil] 

RETURNS [pvID: PhysicalVolume. ID, volumeType: PhysicalVolume. VolumeType]; 
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PhysicalVolume.VoiumeType: type = {notPilot, probablyNotPilot, probablyPilot, isPilot}; 

The returned volumeType gives Pilot's best guess as to the nature of the disk on instance 
in volumeType: notPilot indicates that the disk is definitely not a Pilot physical volume; 
probablyNotPilot indicates that the disk may or may not be a Pilot volume but attempting 
to use the disk as a Pilot physical volume is likely to fail; probablyPilot indicates that the 
disk may not actually contain a Pilot volume, but that an attempt to use it as a Pilot 
physical volume is very likely to succeed; isPilot indicates that the disk almost certainly is 
a Pilot physical volume. In all four cases, pvID is the identifier that the disk appears to 
have and label is the apparent label of the disk (See Physicalvolume.CreatePhysicalVolume 
below for more information about physical volume labels.) It does not matter whether or 
not the access state of the disk has already been asserted. GetHints does not change the 
access state of the disk. GetHints may raise ErrorfnotReady] or Error[invalidHandle] 

As a second facility to aid the client in determining how to access a disk, Pilot permits the 
client read-only , direct access to the device. This allows the client to examine the disk 
safely to determine if it contains a known, but non-Pilot, volume. Such access is provided 
by special Pilot interfaces. 

Given the result of the GetHints operation and of reading the disk, the client can declare 
the access desired to the disk. Upon return from these operations, that the client has the 
indicated access to the disk. 

PhysicalVolume.AssertPilotVolume: procedure [instance: Physicaivoiume. Handle] 

RETURNS (Physicaivoiume .1D] ; 

PhysicalVolume.ErrorType: type = {..., alreadyAsserted,...}; 

AssertPilotVolume asserts to Pilot that the disk contains a Pilot volume. If instance is not 
in the inactive state, Error[alreadyAsserted] is raised. If Pilot's data structures are not in 
order, NeedsScavenging is raised (see Section 4.1.6 on scavenging). Error[notReady] and 
Error[invalidHandle] may also be raised. On return, the disk is in the Pilot-access state 
and the physical volume named by the returned value may be accessed. The returned 
physical volume is said to be online. 

Physicaivoiume. Offline: PROCEDURE [pvID: Physicaivoiume. ID]; 

PhysicalVolume.ErrorType: TYPE as 

{..., containsOpenVolumes, physicalVolumellnknown,.. 

Offline terminates access to an online Pilot physical volume, returning the drive 
containing that volume to the inactive state. All logical volumes contained on the 
physical volume must be closed. This operation may raise 

ErrorfphysicalVolumeUnknown] or Error[containsOpenVolumes] . 

Caution: In the current version of Pilot, if a disk goes not ready while in the Pilot access 
state, the results are unspecified. 
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Non-Pilot access to a disk is initiated and terminated with the following operations. 

Physicaivolume.AssertNotAPilotVolume: procedure [instance: Physicaivoiume.Handle]; 
PhysicalVolume.FinishWithNonPilotVolume: PROCEDURE [instance: Physicaivoiume.Handle]; 
Physicalvolume.ErrorType: type * {..., hasPilotVolume,.. 

AssertNotAPilotVolume initiates direct access to a storage device. If the drive is not 
currently in the inactive state, ErrorfalreadyAsserted] is raised. ErrorfinvalidHandle] 
may also be raised. On return, unlimited access to the device is permitted by Pilot 
through special direct access facilities 

FinishWithNonPilotVolume returns a disk being accessed with non-Pilot access to the 
inactive state. It raises ErrorfhasPilotVolume] if instance currently is in Pilot-access 
mode. It may also raise ErrorfinvalidHandle] 

4.1.5 Physical volume creation 

Pilot disks are created by first creating a physical volume and then creating logical 
volumes upon that physical volume. All storage devices require formatting before their 
first use. (See §8.3.1 for formatting, §4.2.4 for logical volume creation.) A physical 
volume is created by invoking 

» 

Physicalvoiume.CreatePhysicalVolume: procedure [ 
instance: Physicaivoiume.Handle, name: long string] 

RETURNS [PhysicalVolume.lD]; 

Physicalvolurne.maxNameLength: cardinal ■ 40; 

Physicalvolume.ErrorType: type a , badDisk, diskReadError, nameRequired....}; 

This creates a physical volume upon instance. If instance is in the Pilot access state, Pilot 
first calls Offline to place it in the inactive state. This may raise 
Error[physicalVolumeUnknown] or Error(containsOpenVolumes], The label of the newly 
created physical volume is name. The name must contain at least one character or 
ErrorfnameRequired] is raised If the name contains more than maxNameLength 
characters, only the first maxNameLength characters will be used as the label. The newly 
created volume is placed online (i.e , just as if AssertPilotVolume had been called) and its 
ID is returned. If the specified drive is in either the Pilot access state (i.e., online) or in the 
non-Pilot access state, Error[alreadyAsserted] is raised. If Pilot cannot do the necessary 
disk access required to create a physical volume on the disk, Error[badDisk] or 
Error[diskReadError] will be raised. This operation may also raise ErrorfnotReady] and 
ErrorfinvalidHandle]. 

4.1.6 Scavenging 

Scavenging is the process of returning a physical or logical volume to a consistent state. 
This is necessary if the volume was damaged by software errors, pages on the disk went 
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bad, the volume is not of the current version, or the like. Section 4.4 covers scavenging 
logical volumes. A physical volume can be scavenged by invoking 

Physicaivolume.Scavenge: procedure [instance: Physicaivolume. Handle, 
repair: Physicaivolume.RepairType, okayToConvert: boolean] 
returns [status: Physicaivoiume.ScavengerStatus]; 

PhysicaiVolume.RepairType: type « {checkOnly, safeRepair, riskyRepair}; 

Physicaivoiume.ScavengerStatus: type ■ record! 

badPageList, bootFile, germ, softMicrocode, hardMicrocode: 

physicaiVolume.DamageStatus, 
internalStructures: Physicaivolume.RepairStatus]; 

PhysicaiVolume.DamageStatus: type * {okay, damaged, lost}; 

Physicaivolume.RepairStatus: type = (okay, damaged, repaired}; 

Physicalvolume.noProblems: readonly Physicaivoiume.ScavengerStatus ■ ...; 

The purpose of Scavenge is two-fold. First, it allows Pilot to place its internal physical 
volume data structures in order so that client access to the physical volume may be 
permitted. Second, it returns a ScavengerStatus describing any damage found for which 
the client has repair responsibility. Physicaivolume.Scavenge is responsible for the integrity 
of the physical volume only. To repair any logical volume damage, the client must call 
Scavenger. Scavenge. 

If the volume is not of the current version, i.e., not compatible with the Pilot boot file 
which is running, it must be made so before any access is allowed. Invoking Scavenge 
with okayToConvert » true will cause the volume’s version to be increased to the current 
version. This is the only way to cause volume conversion. Scavenging to a previous 
version is not supported, nor is scavenging a volume forward more than one version. 

The physical volume to* be scavenged must be offline. Error[alreadyAsserted] is raised if 
the specified disk drive is online. If the volume version is incorrect and okayToConvert is 
false, Error[need$Conversion] is raised. Error[badDisk] is raised if the damage to the 
physical volume data structures is so great that the physical volume cannot be 
reconstructed. ErrorfinvalidHandle] may also be raised. 

If repair is set to safeRepair or riskyRepair, the scavenger will attempt to repair the 
damage that it finds on the physical volume. The safeRepair mode is limited to repairs 
that are expected to be low risk. The riskyRepair mode imposes no such limits and should 
be used only as a last resort. In particular, it should be used only when the hardware is 
known to be functioning correctly. If repair is set to checkOnly, no repair is attempted but 
a ScavengerStatus indicating any damage is returned. 

The individual status fields have the following meanings: 

badPageList: okay is returned if the bad page list is intact. A status of damaged is 
returned if damage is found and the parameter repair was set to checkOnly. A status 
of lost indicates that damage was found and repair was set to safeRepair or 
riskyRepair. If badPageList = lost, the physical volume scavenger resets the bad page 
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list to empty and marks all logical volumes on this physical volume to be scavenged. 
Bad pages must be marked bad again using a disk utility such as Othello. 

bootFile, germ, softMicrocode, hardMicrocode. okay is returned if the indicated file, 
and the reference to it in the physical volume's data structures, are intact. If the 
status returned is damaged, the indicated file has been found to be damaged. That is, 
there are unreadable pages, missing pages, or the file is otherwise not in valid boot file 
format. The physical volume scavenger will mark the containing logical volume to be 
scavenged. The client should either delete the boot file and reinstall it, or scavenge 
that-logical volume to discover and repair any unreadable or missing pages before 
replacing its contents. If the status returned is lost, the reference to the indicated file 
contained in the physical volume’s data structures appears to be damaged, either 
because the data structures have been damaged or the boot file has been deleted. If the 
file has a unique file type and has not been deleted, the client should be able to find it 
and restore it via OthelloOps.SetPhysicalVolumeBootFile as the appropriate physical 
volume boot, germ, or microcode file. 

internalStructures: the status returned is okay if no damage is discovered in the 
internal data structures of the physical volume. The status returned is damaged if 
damage was found and the parameter repair was set to checkOnly, or if repair was set 
to safeRepair and damage was found that can be repaired only in riskyRepair mode. 
The status is repaired if repair was set to riskyRepair, or if repair was set to safeRepair 
and damage was found which could be repaired safely. 

The constant noProblems is provided to allow the client to determine with a single 
comparison whether it has any work to do after the physical volume scavenger finishes. 

Caution; In Pilot 11.0 the local time parameters may be lost any time the physical 
volume scavenger repairs internal volume structures. This will be the case when 
internalStructures is not reported as okay and repair is set to safeRepair or riskyRepair . It 
is the client's responsibility to reset local time parameters correctly if they have been lost. 

Caution: In Pilot 11.0 the only significant fields of status are badPageList and 
internalStructures. The other fields are always returned as okay, and for them none of the 
validity checking implied is performed. 

4.1.7 Logical volume operations on physical volumes 

The logical volumes on an online physical volume may be enumerated by invoking 

Physkalvolume.GetNextLogicalVolume: procedure [ 
pvID: PhysicalVolume.lD, IvID: System. VolumelD] 

RETURNS [System.VolumelD]; 

This operation is a stateless enumerator. The enumeration begins and ends with 
Volume. nulllD. GetNextLogicalVolume may raise ErrorfphysicalVolumeUnknown] and 
Error[noSuchLogicalVolume], 
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The physical volume that contains a given logical volume is returned by 

Physicalvolume.GetContainingPhysicalVolume: procedure [IvID: System. VolumelD] 

RETURNS [pvID: PhysicalVolume.1 D] ; 

If IvID is unknown to Pilot, volume. Unknown is returned. Note that IvID need not be open 
to invoke this operation. However, it must be in an online physical volume. 

4.1.8 Miscellaneous operations on physical volumes 

The set of online physical volumes is enumerated by 

PhysicalVolume. GetNext: PROCEDURE [pvID: PhysicalVolume. ID] 

RETURNS [PhysicalVolume.1D]; 

This operation is a stateless enumerator. The enumeration begins and ends with 
PhysicalVolume. nulllD. If pvID is not known to Pilot, ErrorfphysicalVolumeUnknown] is 
raised. 

The attributes of an online physical volume may be ascertained by invoking 

PhysicalVolume.GetAttributes: PROCEDURE [pvID: PhysicalVolume.lD, label: LONG STRING NIL] 
returns [instance: PhysicalVolume.Handle, layout: Physicalvolume.Layout]; 

PhysicalVolume. Lay Out: TYPE = 

{partialLogicalVolume, singleLogicalVolume, multipleLogicalVolumes, empty}; 

A handle to the drive containing the physical volume is returned in instance, the label 
name string is returned in label, and the nature of the logical volumes that exist upon 
pvID is returned in layout. If the volume label is longer than the string label, only the 
characters which will fit into the string are returned. A layout value of 
singleLogicalVolume indicates that there is one entire logical volume on pvID; 
multipleLogicalVolumes indicates that there is more than one logical volume upon pvID. 
A value of empty indicates that no logical volumes have been created upon pvID. 
GetAttributes may raise Error[physicalVolumeUnknown]. 

The physical volume name (label) may be changed by invoking 

Physicalvoiume.ChangeNarne: procedure [pvID: PhysicalVolume. ID, newName: long string]; 

If the length of newName exceeds PhysicalVolume. maxNameLength, only the first 
maxNameLength characters are used. If newName does not contain at least one 
character, ErrorfnameRequired] is raised. ChangeName may also raise 
ErrorfphysicalVolumeUnknown]. 

A physical volume may have pages upon it that are unusable (e.g., some sector of the disk 
has failed). Such pages are called bad pages. A page is marked as bad by the operation 

PhysicdiVolume.MarkPageBad: procedure 

[pvID: PhysicalVolume. ID, badPage: Physicaivolume.PageNumber]; 


4-9 


4 


File Storage and Memory 


After a page has been marked bad. Pilot no longer attempts to access it. If a page is to be 
marked as bad, the logical volume containing that page should be closed before invoking 
MarkPageBad. This is not checked by Pilot. Moreover, after this operation returns, that 
logical volume should be scavenged before being opened. Pilot will remember only a 
limited number of bad pages for a given physical volume. If Pilot's table of bad pages, is 
full, Error[badSpotTableFull] is raised and badPage is not remembered as being bad. See 
§8.3 for a description of Pilot facilities for identifying bad pages. MarkPageBad may also 
raise ErrorfphysicalVolumeUnknown]. 

The set of bad pages on a physical volume may be enumerated by invoking 

physicalvoiume.GetNextBadPage: procedure [ 

pvID: PhysicaiVoiume.ID, thisBadPageNumber: PhysicaiVolume.PageNurnber] 
returns [nextBadPageNumber: PhysicaiVolume.PageNurnber]; 

Physicalvolume.nutlBadPage: PageNumber = LASTfPageNumber]; 

This operation is a stateless enumerator. Enumeration begins and ends with 
nullBadPage. GetNextBadPage may raise ErrorfphysicalVolumeUnknown] 

4.2 Logical volumes 

Volume: DEFINITIONS...; 

In this section the term volume , where not specified as logical or physical, will refer to a 
logical volume. 

Before being presented to Pilot for the first time, a volume must be initialized, and it may 
require scavenging or re-initialization after system crashes. Such operations are 
performed using Othello (see the Mesa User's Guide), or by a Oser-written volume 
initializer (See Chapter 8). 

The current version of Pilot supports a maximum of ten logical volumes on a physical 
volume. 

4.2.1 Volume name and size 

The fundamental name for a volume is its ID: 

Volume. ID: TYPE * System. VolumelD; 

Systern.VolumelD: TYPE » RECORD [System. UniversallD]; 

Volume. nulIID: Volume. ID a [System. nulllD]; 

Pilot ensures with a very high probability that each distinct volume is assigned a distinct 
ID No ID is reused for any purpose by any copy of Pilot on any machine at any time. Thus 
a volume may be unambiguously identified by its ID, even if it is moved to another 
machine, or if it is stored offline for a long time. Volume. nulllD is never the name of a 
volume and is used to denote the absence of a volume 
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The maximum size of a logical volume is bytes, or 2- 3 pages. 

volume. maxPagesPerVolume: long cardinal = 8388608; -2 23 

Volume.PageCount: type a longcardinal; -- simulates [0. .volume. maxPagesPerVolume] 
Volume.firstPageCount: volume.PageCount » 0; 

volume.lastPageCount: volume.PageCount a volume.maxPagesPerVolume; 
volume.minPagesPerVolume: readonly Volume.PageCount; 

Note: Because long subrange types are not implemented in the current version of Mesa, 
the current version of Pilot defines Volume.PageCount as a long cardinal, and defines 
constants firstPageCount and lastPageCount to specify FiRSTfPageCount] and 
LASTfPageCount]. These constants should be used rather than the first and last operators, 
which cannot supply the correct value in the case of a simulated subrange. Minimum and 
maximum values are similarly defined for volume.PageNumber below. 

volume.PageNurnber: type a longcardinal; -- simulates [0..volume. maxPagesPerVolume) 

volume.firstPageNumber: Volume.PageNumber = 0; 

volume.lastPageNumber: Volume.PageNumber = volume.maxPagesPerVolume -1; 

4.2.2 Logical and physical volumes 

The correspondence between logical and physical volumes is not dynamic but is 
established at volume initialization time. When a logical volume exists on several 
physical volumes, all of the physical volumes must be available before the logical volume 
is available. Logical volumes permit the simulation of volume sizes not present in 
hardware. For example, several smaller disks can be combined to look like a larger disk. 

Clients should contemplate combining physical volumes into logical volumes only if file 
sizes are likely to exceed the size of an individual physical volume. Pilot offers no recovery 
if one of the physical volumes comprising a logical volume is lost or destroyed. The 
contents of the remaining physical volumes are, in general, irretrievable. 

Note: There is no mechanism to create a logical volume which spans multiple physical 
volumes. 

There is one volume known as the system volume , intended to be used as the default 
volume by Pilot and its clients. The system volume is the logical volume which contains 
the boot file of the system being executed. The ID of this volume is contained in 

Volume.systemID: readonly volume.lD; 

Note: In Utility Pilot-based systems there is no system volume. Volume.systemID will have 
the value volume.nulllD 
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4.2.3 Volume error conditions 


The following errors may be raised during many volume operations. The description of 
each operation indicates which errors it can raise. 

volume.Unknown: error [volume: Voiume.lD]; 

Unknown is raised when a volume is not known to Pilot. No part of the volume is online. 
Unknown will be raised if Volume. nulIlD is used for any operation except those which start 
an enumeration. 

volume.NotOnline: error [volume: volume. ID]; 

NotOnline indicates that a volume is only partially online, i.e., not all of the physical 
volumes comprising the volume are online. 

volume. NotOpen: error [volume: Voiume.lD]; 

Operations which require the volume to be open raise NotOpen if the volume is partially 
online or online but closed. 

volume.ReadOnly: error [volume: Voiume.lD]; 

Attempting to change the contents of a volume which is open for reading but not writing, 
will cause Readonly to be raised. 

volume.NeedsScavenging: error [volume: Voiume.lD]; 

NeedsScavenging indicates that Pilot data structures on the volume are inconsistent or 
incorrect. This can occur as a result of a system crash, or the volume may have the format 
of an incompatible version of Pilot, or the volume may not in fact be a Pilot volume. 

volume.lnsufficientSpace: error [ 

currentFreeSpace: volume.PageCount, volume: Voiume.lD]; 

The error InsufficientSpace is raised when there is not enough space left in the volume for 
the requested operation to complete. The number of pages actually available is returned 

in currentFreeSpace. 

volume.Error: error [error: Volume. ErrorType]; 
volume.ErrorType: type ■ {.. 

The specific values for Error are defined below as they occur in the text. 

4.2.4 Creating and erasing logical volumes 

A logical volume can be created on a physical volume by invoking 

volume. Create: procedure [ 

pvID: System. PhysicalVolumeiD, size: volume.PageCount, name: long string. 
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type: volume. Type, mmPVPageNumber: Physicaivoiume.PageNurnber 1] 

RETURNS [volume: Volume.iD]; 

Physicaivolume.maxSubvolumesOnPhysicalVolume: readonly cardinal; 

volume.maxNameLength: cardinal ■ 40; 

volume.Type: type * machine dependent 

{normal(O), debugger(l), debuggerDebugger(2), nonPilot(3)}; 

volume.ErrorType: type ■ {nameRequired, pageCountTooSmallForVolume, 
subvolumeHasTooManyBadPages, tooManySubvolumes}; 

This creates a new logical volume on pvID of type type and containing size pages. (See 
§4.2.6, Opening and closing volumes, for a discussion of the significance of volume types.) 
The volume label, which can be used to identify the logical volume, is name. The label is 
not used by Pilot. Only the first Volume.maxNameLength characters of name are used. 
The newly created volume will not overlap any other logical volumes upon pvID. Logical 
volumes occupy one or more contiguous, disjoint regions of physical volumes. The volume 
will start at a page number at least as large as page minPVPageNumber of pvID; it may 
start later. 

If this new volume will cause the number of subvolumes to exceed 
maxSubvolumesOnPhysicalVolume, Error[tooManySubvolumes] will be raised. If pvID is 
not a valid physical volume, Physicalvolume.ErrorfphysicalVolumeUnknown] is raised. If 
size is not enough pages to make a volume, ErrorfpageCountTooSmallForVolume] is 
raised. If there is insufficient unused space on pvID to create the logical volume, 
PhysicalVolume.Error[insufficientSpace] will be raised. If name is nil or its length is zero, 
Error[nameRequired] is raised. If there are too many bad pages on the area of the disk to 
be used for the proposed logical volume, ErrorfsubvolumeHasTooManyBadPages] to be 
raised. Hardware errors encountered in creating the volume will cause 
PHysicalVolume.ErrorfhardwareError] to be raised. 


A logical volume may be erased, destroying its previous contents, by invoking 

volume.Erase: procedure [volume: Volume.iD]; 

Volume volume may be online or open when this operation is invoked, and Erase does not 
affect this status. Erase may raise the errors Unknown, NotOnline, Readonly, or 
Phy$icalVolume.Error[hardwareError]. 

4.2.5 Volume status and enumeration 

The logical volumes of an online physical volume may be enumerated by 

PhysicalVolume.GetNextLogicalVolume (see §4.1.7). 

A client may determine the status of a logical volume by calling 

volume.GetStatus: procedure [volume: Volume.iD] returns [volume. Status]; 
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volume. Status: type s {unknown, partiallyOnLine, closedAndlnconsistent, 
dosedAndConsistent, openRead, openReadWrite}; 

The meaning of each Status is as follows, unknown indicates that no part of volume is 
contained in an online physical volume. partiallyOnLine indicates that the volume spans 
multiple physical volumes and at least one of those physical volumes is offline. 
closedAndlnconsistent means that all parts of volume are online but it needs scavenging 
before it can be opened. dosedAndConsistent means all parts of volume are online, and it 
is closed and does not need scavenging. openReadWrite indicates that volume is open and 
accessible for both reading and writing. openRead indicates that the volume is open only 
for reading. 

Clients can discover the identities of online or open logical volumes by calling 

voiume.GetNext: procedure [volume: votumeJD, 

includeWhichVolumes: volume. TypeSet onlyEnumerateCurrentType] 

RETURNS [nextVolume: Volume.lD]; 

volume.TypeSet: type » packed array volume.Type of volume.BooleanDefaultFalse; 
voiume.BooleanDefaultFalse: type * boolean «- false; 
volume.onlyEnumerateCurrentType: volume.TypeSet = []; 

GetNext is a stateless enumerator with a starting and ending value of volume. nuMD It 
enumerates the logical volumes of the type(s) specified by includeWhichVolumes which 
are currently online or open. GetNext may raise the error Unknown. 

4.2*6 Opening and closing volumes 

When a Pilot boot file is invoked, the system physical volume and system logical volume are 
the physical and logical volumes containing the boot file. During its initialization, Pilot 
brings the system physical volume online and opens the system logical volume, 
scavenging it if necessary. If the logical volume version is not current (compatible with the 
Pilot boot file which is running), initialization scavenging will cause it to be converted to 
the current version. 

Note: For Utility Pilot-based systems there is no system physical or logical volume, and 
no physical or logical volumes are brought online. 

A client may open an online volume, making its files accessible, by calling 

Volume.Open: PROCEDURE [volume: Volume.lD]; 

Once a volume is open, the client may create, read, write, and delete files on the volume. 
Opening an already open volume is a no-op, A volume will be opened read-only if the 
volume being opened is of a higher Volume.Type than the system volume. This will be the 
case if, (a) the system volume is of type normal, and volume is of type debugger or 
dehuggerDebugger, or (b) the system volume is of type debugger and volume is of type 
debuggerDebugger 
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Note: For UtilitvPilot-based systems volumes are always opened read-write. 

An attempt to write on or otherwise change the state of a read-only volume will cause 
Readonly to be raised. Other errors which may be raised by Open are Unknown, 
NotOnline, and NeedsScavenging. 

Caution: If a debugger opens (for read-write) any volume which its debuggee currently 
has open, that debuggee should not be allowed to continue execution. Opening the volume 
changes its state, and the debuggee’s Pilot will have out-of-date information about the 
volume. Continuing its execution in this case will have unpredictable (and undesirable) 
results. 


The client may close an open volume by calling 
Volume.Close: PROCEDURE [volume: Volume.ID]; 

This operation assures that the volume is in a a physically consistent state. The data on 
the volume will no longer be accessible. Closing a closed volume is a no-op Close may 
raise errors Unknown and NotOnline. 

4>2.7 Volume attributes 

Volumes have attributes which can be examined and some of which can be set. 

Voiume.GetAttributes: procedure [volume: volume.lD] 

returns [volumeSize, freePageCount: Volume.PageCount, readonly: boolean]; 

This operation may be applied to any online or open volume. The attributes volumeSize 
and freePageCount indicate the number of pages and free pages, respectively, of the 
volume. freePageCount is the maximum length file that can be created, or the maximum 
by which the size of a file may be grown, at that time. Because the space reflected by 
freePageCount must also be used for Pilot internal data structures, it may not be possible 
to create or extend a file by precisely this much. In general, the amount of free space left 
after creating or extending a file cannot be predicted exactly, readonly is TRUE if the 
volume is open for reading but not writing, i.e., if it is of a higher volume. Type than the 
system volume. GetAttributes may raise Unknown, NotOnline, and NeedsScavenging. 

The ID of the volume that contains the debugger is kept in 

voiume.debuggerVolurnelD: readonly volume. ID; 

If it is equal to Volume. nulllD, there is no debugger present on a local volume. In 
Utility Pilot-based systems, debuggerVoiumelD is always nulllD. 


The type of an online or open volume may be ascertained with the procedure 

Volume.GetType: procedure [volume: volume. ID] returns [type: volume. Type]; 
GetType may raise errors Unknown, NotOnline, and NeedsScavenging. 
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The volume label is set when a volume is created. The label can be used bv the client to 
identify the logical volume, but it is not significant to Pilot. The label of an online or open 
volume may be changed by the following operation. 

volume.ChangeLabelString^ procedure [volume: volume.lD, newLabel: long string]; 

Only the first volume. maxNameLength characters of newLabel are used. If newLabel is nil 
or its length is zero, Error[nameRequired] is raised. ChangeLabelString may raise 
Unknown, NotOnline, Readonly, and NeedsScavenging. 

The label of an online or open volume may be retrieved by the following operation. 

volume.GetLabelString: procedure [volume: voiume.lD, s: long string]; 

If the length of the volume label exceeds that of s, the returned label will contain only as 
many characters as will fit. The length will not exceed maxNameLength. GetLabelString 
may raise Unknown, NotOnline, and NeedsScavenging. 

4.2.8 Volume root directory 

The volume root directory provides a mechanism for client file systems to retain a File.File 
for the root of their file system. It provides a mapping from a File.Type into a File.File. For 
any given File.Type there can be at most one root file. A File.Type of FileTypes.tUntypedFile 
functions as a null value for the root directory operations. The operations in this section 
allow manipulation of an open volume’s root directory. 

volume.RootDirectoryError: error [type: volume.RootDirectoryErrorType]; 

Volume.RootDirectoryErrorType: type = 

{directoryFull, duplicateRootFile, invalidRootFileType, rootFileUnknown}; 

Root directory operations may raise the error RootOi rectory Error. Individual errors are 
described with the operations that raise them. All of the root directory operations may 
also raise Unknown, NotOnline, and NotOpen, and NeedsScavenging. 

Inserting a file into the volume root directory is accomplished by 
volume.lnsertRootFile: procedure [type: File.Type, file: File.File]; 
volume.rnaxEntriesInRootDirectory: readonly cardinal; 

If the root directory already has an entry for type, RootDirectoryError[duplicateRootFile] 
is raised. The root directory is of fixed size. If the insertion would result in more than 
maxEntriesInRootDirectory entries, RootDirectoryError[directoryFull] is raised. An 
attempt to insert a file with type FileTypes.tUntypedFile into the root directory results in 
the error RootDirectoryError[invalidRootFileType]. Readonly may also be raised. 
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volume.RemoveRootFile: procedure ( 

type: File. Type, volume: volume. ID volume. SystemlDj; 

The entry for a given File. Type may be removed from the root directory by 

RemoveRootFile. It may raise RootDirectoryError[rootFilel)nknown] and Readonly. 

volume.LookllpRootFile: procedure [type: File.Type] returns [file: File. File]; 

The file previously stored for a given file type may be retrieved by calling LookllpRootFile. 

If there is no entry in the root directory for that type, 

RootDirectoryErrorfrootFileUnknown] is raised. 

voiume.GetNextRootFile: procedure [ 

lastType: File.Type, volume: volume.lD <— volume.SystemID] 
returns [file: File.File, type: File.Type]; 

The set of root files in the root directory may be enumerated by calling the stateless 

enumerator GetNextRootFile. The enumeration begins and ends with 

FileTypes.tUntypedFile. It may raise RootDirectoryError[rootFileUnknown], 


4.3 Files 


File: DEFINITIONS...; 

FileTypes: definitions ...; 

CommonSoftwareFileTypes: definitions ...; 

A file is the basic unit of long-term information storage. A file consists of a sequence of 
pages, the contents of which can be preserved across system restarts. Files are named by 
specifying the containing volume, and by a file identifier which is unique within that 
volume. The operations described in this section enable clients to create and destroy files, 
and to examine and set their attributes. 

4.3.1 File naming 

A file is named by giving the identifier of the volume on which it resides and the ID of the 
file: 

File. ID: type [2]; 

File.File: type * record [filelD: File.ID, volumelD: System.VolumelD]; 

File.nulllD: File.ID m — "null ID 19 

File.nullFile: File.File * [File.nulllD, [System. nulllD]]; 

File. IDs are unique within any single volume. Since Pilot ensures with a very high 
probability that each distinct volume is assigned a distinct volume identifier, the 
combination of a volume identifier and a File. ID in a File.File is similarly unique. Pilot will 
normally create files with File. IDs which have never appeared on the containing volume. 
However, Pilot may reuse the File.IDs of deleted files under some circumstances. File.nulllD 
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is never allocated as the ID of a file, and will cause the error File, Unknown to he raised if 
used for any operation except those that start an enumeration. File.nullFile may be used to 
denote the absence of a file. 

All File operations require the volume containing the file to be open. 

4*3.2 Addressing within files 

Pilot fi’es may hold up to 2 32 bytes (2 2 $ pages) and may be randomly accessed on a page- 
by-page basis. All addresses within a file are in terms of page numbers, representing 
offsets (in pages) from the beginning of the file. The first page of a file is page number 
zero. 

File.PageNumber: type = long cardinal; - simulates [0.File.maxPagesPerFile) 
File.maxPagesPerFile: long cardinal = 8388607; - 2 2 *-1 
File.firstPageNumber: File.PageNumber ■ 0; 

File.IastPageNumber: File.PageNumber = File.maxPagesPerFile -1; 

Note: Because LONG subrange types are not implemented in the current version of Mesa, 
the current version of Pilot defines .PageNumber as a long cardinal and defines constants 
firstPageNumber and lastPageNumber to specify F«RST[PageNumber] and 
LAST[PageNumber]. These constants should be used rather than the first and last 
operators, which cannot supply the correct value in the case of a simulated subrange. 
Minimum and maximum values are similarly defined below for File.PageCount. 

File.PageCount: type = long cardinal; - simulates [0..File.maxPagesPerFile] 

File.firstPageCount: File.PageCount = 0; 

File.lastPageCount: File.PageCount = File.maxPagesPerFile; 

4.3.3 File types 

InPilot, every file must be assigned a file type at the time it is created. A file type is of type 
File.Type and is constant for the life of the file. It provides a means for Pilot, various 
scavenging programs, and clients to recognize the purpose for which each file was 
intended. This is especially important because files on Pilot disks do not inherently have 
meaningful strings for names, making it difficult for a human user or programmer to 
recognize which file is which. To make this principle work effectively, each different kind 
of file should be assigned its own unique type. See Appendix B for an explanation of how 
file types are assigned and managed. 

File types are intended to be used by Pilot clients in distinguishing the types of objects 
represented by Pilot files. Each specific application may assign its own type to its own 
files, either for redundancy or for control of the processing of those files. 

File types are allocated by the Manager of System Development and are defined as follows: 
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File. Type: type = record [caroinal]; 

The center of this scheme is the FileTypes interface, maintained by the Pilot group. In this 
file are defined all subranges of File. Type assigned to individual client and application 
groups. This module is designed so that it can be recompiled whenever a new type is 
assigned without invalidating any old version. Thus, within certain limits, a program 
may include any version of FileTypes which contains the file types of interest to it without 
building in an unnecessary or awkward compilation dependency. 

The basic structure of FileTypes is a set of subrange and constant definitions. The following 
ranges are defined. (The reader should consult the documentation of the appropriate 
system to see how the specific file types have been defined): 

FileTypes.MesaFileType: type a cardinal!...]; 

FileTypes. DCSFiieType: type = cardinal!...]; 

FileTypes.TestFileType: type « cardinal [. . .]; 

FileTypes.SBSOFileType: type = cardinal I.. .]; 

FiieTypes.CommonSoftwareFileType: type = cardinal [. . .]; 

FileTypes.DocProcFileType: type = cardinal [. . .]; 

FileTypes.FileServiceFileType: type = cardinal [. . .]; 

FileTypes.ServicesFileType: type = cardinal [. . .]; 

FileTypes.MesaDEFileType: type = cardinal [. . .]; 

FileTypes.PerformanceToolFileType: type = cardinal [. . .]; 

FileTypes.DiagnosticsFileType: type = cardinal [...]; 

FileTypes.CADFileType: type = cardinal [. . .]; 

FileTypes.CedarFileType: type = cardinal I.. .]; 

FileTypes.VersatecFileType: type = cardinal {...]; 

Mesa file types are used by Mesa source and object files. DCS file types are used by 
development common software. Test file types are used by the test tools. SBSO file types 
are used by OPD Small Business Systems Operation. Common Software file types are 
used by product common software. File service file types are used by the file server. 
Printing service file types are used by the print server. MesaDE file types are used in the 
Mesa development environment. Performance tool file types are used to store binary data 
typically generated by performance tools. Diagnostics file types are used by diagnostics 
software. CAD file types are used by computer aided design software. Cedar file types are 
used by the PARC Cedar project. Versatec file types are provided for the use of Versatec. 

The type 
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FileTypes.tUntypedFile: File.Type * [last[cardinal]]; 

may be used as a null value, denoting the absence of a type. This is not enforced by Pilot 
however. 

The following common software file types are defined in the range 

CommonSoftwareFileType: 

CommonSoftwarePileTypes.tUnaSSigned: File.Type a [. ..]; 

CommonSoftwareFileTypes.t Directory: File.Type a [...]; 

CommonSoftwareFileTypes.tBackstOpLog: File.Type = 
CornnuonSoftwareFileTypes.tCarryVolumeDirectory: File.Type a [...]; 
CommonSoftwareFileTypes.tClearingHouseBackupFile: File.Type a [...]; 
CommonSoftwareFileTypes.tFilelist: File.Type a [...]; 
CommonSoftwareFileTypes.tBackstOpDebugger: File.Type a [.. 
CommonSoftwareFileTypes.tBackstOpDebuggee: File.Type a [...]; 

These are mostly self-explanatory, tDirectory is obsolete. tFilelist is the file type of the 
file list used by the Floppy file system (see §5.5). 

4.3.4 File error conditions 

The following errors may arise during file operations: 

File.Error: error [type: File.ErrorType]; 

File.ErrorType: type = {invalidParameters, reservedType}; 

Most file operations raise Error. Error[invalidParameters] is raised by operations 
when the parameters specify an illegal condition. Error[reservedType] is raised 
when one of Pilot's reserved file types is used improperly. 

File.Unknown: error [file: File. File]; 

Unknown indicates that the file does not exist on the given volume. It is also raised if 
File.nullFile is supplied to any operation except a stateless enumerator. 

File. MissingPages: error [ 

file: File.File, firstMissing: File.PageCount, countMissing: File.PageCount]; 

MissingPages indicates that the specified pages are missing from the file due to an 
exceptional condition, usually a disk hardware error. This error is not raised by any File 
operation, but is raised by other Pilot operations. 
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File operations may raise the errors volume. Unknown, Volume. NotOnline, Volume. NotOpen, 
volume. InsufficientSpace, and volume. Readonly. 


4.3.5 File creation and deletion 

To create a new file on a volume, call the procedure: 

File.Create: procedure! 

volume: System.VolumelD, initialSize: File.PageCount, type: Fiie.Type] 
returns [file: Fiie.File] 

A Fiie.File for the new file is returned. Files are created as temporary files. The file initially 
contains the number of pages specified by initialSize (filled with zeros). Pilot attempts to 
allocate contiguous space on the volume, if such is available. There are significant 
performance penalties associated with increasing the size of a file. Programmers should 
make every attempt to create the file with the size it will eventually be. If initialSize is 
zero or greater than File.maxPagesPerFile, ErrorfinvalidParameters] is raised. If there is not 
enough space on the volume to contain the file, Volume. InsufficientSpace is raised. 
Volume.ReadOnly is raised if the volume is open for reading only. 

The type attribute of the file is a tag provided by Pilot for the use of higher level software. 
If type is one of a set of values reserved by Pilot, ErrorfreservedType] is raised. 

* 

By creating a file on an empty volume, creating a second file, and so on, a client program 
can construct a set of files all of whose space is guaranteed to be contiguous. 

A file is deleted by the operation 

Fiie.Delete: procedure [file: Fiie.File]; 

The file is deleted permanently; no "undelete" operation exists. File.Unknown is raised if 
there is no such file on the volume. Volume.ReadOnly is raised if the volume is open for 
reading only. 

Caution: The file being deleted must not contain any file windows for mapped spaces (see 
§4.6.2); the behavior of Pilot in such circumstances is undefined. 

4.3.6 File attributes 

Aside from its name and contents, a file has three other attributes: size, type, and 
temporary/permanent status. These can be examined using the operations defined below. 
All of these operations may raise File.Unknown. 

The size of a file may be ascertained by calling 

File.GetSize: procedure [file: Fiie.File] returns [size: File.PageCount]; 

The size of a file may be altered by calling 

File.SetSize: procedure [file: Fiie.File, size: File.PageCount]; 
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If the .size is increased. Pilot attempts to allocate disk space physically adjacent to the end 
of the file, and it also attempts to allocate a contiguous sequence of pages, if such is 
available. Any new pages of the file are filled with zeros. Attempting to set the size to zero 
or greater than File.maxPagesPerFile will cause ErrorfinvalidParameters] to be raised. 
Voiume.ReadOnly will result if the volume is readonly, and volume.InsufficientSpace will be 
raised is there are not enough free pages on the volume for the new file size. 

Extending a file is a fairly expensive operation. It is better for a client to determine the 
ultimate amount by which a file is to be extended, and do it all at once rather than to 
increase its size a page or two at a time. This both reduces the amount of disk traffic and 
increases the likelihood that Pilot will be able to allocate a contiguous sequence of pages 
for the extension. There are also continuing performance penalties for accessing a 
fragmented file, which may result from growing the file one or more times. 

Caution: For a file which is being shrunk, the pages being deleted must not be mapped 
into virtual memory. The behavior of Pilot in such circumstances is undefined. 

The rest of the attributes of a file can be inspected collectively by calling 

File.GetAttributes: procedure [file: File.File] 
returns [type: File.Type, temporary: boolean]; 

The temporary attribute indicates whether the file is temporary or permanent. Pilot 
deletes temporary files when the volume is next booted, scavenged, or opened/for writing. 
Permanent files are preserved across system restarts. A file is always created as 
temporary. A file may be made permanent by calling the operation 

File.MakePermanent: procedure [file: File.File]; 

A file should not be made permanent before the client has safely stored the File.File for that 
file in some client-level directory or other permanent data structure. The scavenger (§ 4.4) 
provides means for recovering a permanent file for which the File.File has been lost. 

The intended sequence for making a permanent file is as follows: When a client creates a 
file, it is temporary. The client then stores the File.File for that file in a safe place, doing 
Space.ForceOut on the safe place to guarantee that it is written into the backing file. The 
client then makes the file permanent using File.MakePermanent. 

4.4 Scavenging 

Scavenger: definitions ...; 

The act of repairing an inconsistent or damaged Pilot logical volume is known as 
scavenging. A Pilot logical volume may become damaged for any number of reasons. A 
machine that is using the volume may stop abnormally due to hardware or software 
failure. The drive containing the volume may fail and damage the volume, or the physical 
medium containing (part of) the volume might fail. A damaged volume may not be 
accessed until it has been repaired. This is enforced at the time that volume. Open is called. 
If the volume is detected as damaged by Pilot, volume. NeedsScavenging is raised. A 
volume is repaired using the Scavenger interface 
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4.4.1 Scavenging a volume 

A damaged volume is repaired by the operation 

Scavenger.Scavenge: procedure (volume, logDestination: volume. ID, 
repair: Scavenger.RepairType, okayToConvert: boolean] 
returns (logFile: File. File]; 

Scavenger.RepairType: type ■ machine dependent {checkOnly(O), 
safeRepair(l), riskyRepair(2)}; 

Scavenger.Error: ERROR [error: Scavenger.ErrorType]; 

Scavenger. ErrorType: type » {..., volumeOpen, cannotWriteLog, 
needsRiskyRepair, needsConversion,.. 

The purpose of the Scavenge operation is two-fold. First, it allows Pilot to place its own 
data structures in order so that client access to the volume may be permitted. Second, it 
produces a log file (described below) describing the state of the volume. The log file is 
intended to be used by client-level scavengers to reconstruct client data structures. 

The volume to be scavenged is given by volume. If volume is open, the error 
Error[volumeOpen] is raised. The log file is created on the volume logDestination. If 
logDestination equals volume, the created log file is permanent; otherwise, the log file is 
temporary. Volume logDestination must be open if it is not the same as the volume to be 
scavenged. Scavenge may also raise volume.NotOnline and Volume.Unknown, 

The level of repair attempted by the scavenger is governed by the value of repair A value 
of checkOnly causes a log file to be produced but no repair is done. In this case, it is 
advisable to specify logDestination 4 to be a volume different from the scavengee since it 
may not be possible to build a log file on a damaged volume. If repair is safeRepair, the 
scavenger will attempt to repair the damage that it finds upon the volume. This is the 
normal usage. If Pilot is unable to repair the volume satisfactorily in this mode, 
Error[need$RiskyRepair] is returned. Certain forms of repair are performed only if repair 
is equal to riskyRepair. Scavenging in riskyRepair mode should be attempted only after 
the hardware has been verified to be working correctly. 

Caution: In the current version of Pilot, repair equal to checkOnly is not implemented. 

okayToConvert determines whether conversion of a volume of an incompatible version 
will occur. A volume is of an incompatible version if its format is not compatible with the 
Pilot boot file which is running. If okayToConvert is true scavenging will convert a 
volume from the previous version to the current one. If the volume version is incompatible 
but okayToConvert is false, Error[needsConversion] is raised. Scavenging to a previous 
version is not supported, nor is scavenging a volume forward more than one version. 
okayToConvert is set to false during pilot initialization, causing the system logical 
volume to not be converted forward. 

If a previous log file for this volume exists, Pilot attempts to delete it after Pilot data 
structures have been repaired, but before a new log is written. This delete is comparable 
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to a call on the DeleteLog operation (see below). If Pilot is unable to write the log for any 
reason, ErrorfcannotWriteLogJ is returned and no scavenging is done. 

Caution: In the current version of Pilot, the volume is repaired even if cannotWriteLog is 
raised. 

During Pilot initialization, the system logical volume is scavenged as necessary with 
repair ■ safeRepair and okayToConvert * true. The resulting log file is placed on the 
system volume. 

4.4.2 Scavenger log file 

A log file describes the state of a volume after the Scavenge operation has been invoked. It 
contains information about the volume and the outcome of the Scavenge as well as a list of 
all files on the volume and the problems, if any, with each file. A log file contains a data 
structure of type LogFormat. 

Scavenger. LogFormat: TYPE = MACHINE DEPENDENT RECORD [ 
header: Scavenger. Header, 
files: array [0..0) of FileEntry]; 

Scavenger. Header: TYPE = MACHINE DEPENDENT RECORD [ 
seal: CARDINAL «- Scavenger. LogSeal, 
version: cardinal «- Scavenger.currentLogVersion, 
volume: volume.lD, 
date: System.GreenwichMeanTirne, 
repair Mode: Scavenger.RepairType, 
incomplete: boolean, 
repaired: boolean. 

bootFilesDeleted: Scavenger. BootFileArray, 
pad: [0..0J «-0, 

numberOfFiles: long cardinal]; 

Scavenger.LogSeal: CARDINAL = 130725B; 

Scavenger.currentLogVersion: cardinal = 1; 

Scavenger.BootFileArray: TYPE = 

PACKED ARRAY Scavenger.BOOtFileType OF BOOLEAN; 

Scavenger. BOOtFileType: TYPE = MACHINE DEPENDENT { 

hardMicrocode(O), softMicrocode(l), germ(2), pilot(3), debugger(4), debuggee(5)}; 

Scavenger. noneDeleted: Scavenger.BootFileArray = all[false]; 

Scavenger. FileEntry: TYPE = MACHINE DEPENDENT RECORD [ 
file: Fiie.lD, 

sortKey: long cardinal, 
numberOfProblems: cardinal, 
problems: array [0..0) of Scavenger. Problem]; 
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Scavenger. Problem: TYPE = MACHINE DEPENDENT RECORD [ 
trouble: select entryType: Scavenger. EntryType from 

unreadable, missing = > [first: File.PageNumber, count: File.PageCount), 

duplicate, orphan = > [id: Scavenger.OrphanHandle] 

endcase]; 

Scavenger.EntryType: TYPE = MACHINE DEPENDENT { 

unreadable(O), missing(l), duplicate(2), orphan(3)}; 

Scavenger.OrphanHandle: type [2]; 

Scavenger.tScavengerLog: readonly File.Type; 

Scavenger.tScavengerLogOtherVolume: readonly File.Type; 

The log consists of a Header followed by zero or more FileEntrys. The Header describes the 
scavenged volume and the outcome of scavenging. The seal field is used to verify that a 
file is in fact a scavenger log; its value should be LogSeal. The version is the log file 
format version; its value should be currentLogVersion The scavenge occurred on volume 
volume at time date with the value of the repair argument which was passed to the 
Scavenge operation equal to repairMode If incomplete is true, the file list may not 
include all files or problems due to insufficient space on the log destination volume or 
overflow of the internal tables used when scavenging. The header is always complete. A 
value of true for repaired indicates that all volume structures are in order and the volume 
may be accessed. If it was necessary to delete one or more boot files in order to complete 
the scavenge, the elements of bootFilesOeleted corresponding to the deleted boot files will 
be TRUE. Boot files are deleted only in very unusual situations. The count of files on the 
scavenged volume is given by numberOfFiles. 

Following the header are Header.numberOfFiles contiguous entries of type FileEntry. In 
each entry, file identifies the file, sortKey is a sort accelerator for client scavengers , and 
numberOfProblems is the number of problems associated with the file. If 
numberOfProblems is not zero, problems contains one Problem entry for each problem 
encountered. Note that some files will be absent from the list if.header.incomplete is true. 

There are four categories of problem: unreadable pages, missing pages, duplicate pages, 
and orphan pages. If the data portion of a sequence of file pages is unreadable or the label 
can be read correctly, but is either self-inconsistant or is inconsistant with the rest of the 
file, an unreadable Problem entry is entered in the log. If a sequence of file pages is 
missing, a missing Problem entry is created. If a page has an unreadable label, it cannot 
be associated with any file and is reported as an orphan Problem of a FileEntry which has 
file equal to File.nulllD Finally, if there are two or more pages claiming to be the same 
page of a file, one is arbitrarily chosen as the actual file page. The rest are reported as 
duplicate Problem entries. A page identified as orphan or duplicate is provided a 
Scavenger.OrphanHandle in the problem entry so that the page may be accessed. The size of 
a Problem entry in the log is always siZEfProblem]. 

The scavenger cannot detect the absence of one or more pages from the very end of a file. It 
is the client's responsibility to deal with failures of this nature. If only the first page of a 
file is missing. Pilot assumes that the file is permanent. Missing or unreadable pages 
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should be accessed only via operations provided by the Scavenger interface for dealing with 
such pages and not bv, e.g., Space.Map 

A scavenger log file built upon the volume being scavenged will be of file type 
tScavengerLog. A log file written to a different volume will have type 

tScavengerLogOtherVolume, 

A log file may also be generated by the following operation: 

Scavenger. MakeFileList: PROCEDURE [volume, logOestination: volume. ID] 
returns [logFile: File. File]; 

This procedure will generate a Log for the volume volume without the overhead of 
actually scavenging the volume. If either of the specified volumes is not open, 
Volume.NotOpen is raised. Volume. Unknown is raised if either volume is unknown. The 
resulting log will be the same form as a log generated by Scavenge except that no 
problems are reported. The log file is not an "official” log file, i.e., it is not affected by 
Scavenge, GetLog, or DeleteLog. The returned file is a temporary file; it is the client’s 
responsibility to make it permanent if that is appropriate. 

Caution; The client should not create or delete files from volume while MakeFileList is in 
process or the log may be incomplete or incorrect. 

4.4.3 Operations on log files 

The current log file for an open volume, as produced by the most recent invocation of 
Scavenger.Scavenge[volume f ...], is returned by 

Scavenger. GetLog: PROCEDURE [volume: Volume. ID] 
returns [logFile: File.File]; 

If there is no log file, File.nullFile is returned. Even if the returned logFile is not File.nullFile 
the log file will not exist if it has been deleted by some means other than a 
Scavenger. DeleteLog. Thus, the client must be prepared to catch the signal File.Unknown 
while accessing logFile. GetLog may also raise Volume.NotOpen, Volume.NotOnline, or 
Volume.Unknown. 


The current log file for an open volume may be deleted by 
Scavenger.DeleteLog: PROCEDURE [volume: Volume. ID]; 

volume is the volume which was scavenged to produce the log file. The log file may be on 
volume or it may be on another volume, depending on the log destination chosen for the 
Scavenge. If the volume containing the log file is not open for writing, the file is not 
deleted. Subsequent GetLog operations on volume return File.nullFile until 
Scavenge[volume, . . .] is called again DeleteLog does not affect log files generated by 
MakeFileList. DeleteLog may also raise Volume.NotOpen, volume.NotOnline, 
Volume.Unknown, or volume.Readonly. 
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4.4.4 Investigating and repairing damaged pages 

The damage reported in the log file may be investigated and repaired through the use of 
the following operations. All of these operations require the volume to be open. All of the 
operations raise Fite. Unknown if the specified file cannot be found, and Volume. NotOpen, 
Volume. NotOnline, or volume. Unknown for the specified problem with the volume. Those 
which change volume contents may raise Volume. Readonly. 

An unreadable page, as described by an unreadable Problem entry, may be read by 

Scavenger.ReadBadPage: procedure [ 

file: File.File, page: File.PageNumber, destination: Space. PageNumber] 
returns [readErrors: boolean]; 

Scavenger.ErrorType: type a {..., diskHardwareError, diskNotReady, 
noSuchPage,.. .}; 

The contents of page page of file are read into virtual memory page destination which 
must be mapped and writable. (An address fault or write protect fault is indicated if it is 
not.) The effect is to overwrite the previous contents of destination with the contents of 
the specified file page. The returned value readErrors indicates whether or not any error 
was encountered while accessing the specified file page. Read errors that occur while 
reading page affect only the value of readErrors and are otherwise ignored. If the read 
encountered errors, the data is not guaranteed to be reliable.If page does not exist or lies 
beyond the end of file, Error[noSuchPage] is raised. If the target disk is not ready, 
Error[diskNotReady] is raised. If the target disk reports a drive-level failure (as opposed to 
a page-level failure such as a read error), ErrorfdiskHardwareError] is raised. 

An unreadable page may be rewritten or a missing page may be replaced by 

Scavenger. RewritePage: procedure [ 

file: File.File, page: File.PageNumber, source: space.PageNumber] 
returns [writeErrors: boolean]; 

The current contents of page page of file are overwritten by virtual memory page source, 
which must be mapped. The original disk page is reused if it is present (to replace a file 
page, use ReplaceBadPage below); if the original page is missing, Pilot will allocate a new 
page for that file page. The return value writeErrors indicates whether or not errors were 
encountered while trying to rewrite the specified page. If writeErrors returns false, the 
page should be considered to be rehabilitated. Clients should first attempt to rewrite bad 
file pages using RewritePage. If this fails repeatedly, the client should use 
ReplaceBadPage to rewrite the file page in a different backing page. 

If page is beyond the end of file, ErrorfnoSuchPage] is raised. If no page can be allocated to 
replace a missing page, Volume. InsufficientSpace is raised. If the target disk is not ready, 
ErrorfdiskNotReady] is raised. If the target disk reports a drive-level failure, 
ErrorfdiskHardwareError] is raised. An address fault will result if source is not mapped. 


The following procedure also rewrites a bad page in a file, but in addition it discards the 
disk page that the file currently occupies and allocates a new one: 
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Scavenger.ReplaceBadPage: procedure [ 

file: File.File, page: Fiie.PageNumber, source: Space.PageNumber] 
returns [writeErrors: boolean]; 

ReplaceBadPage will allocate a new page for the specified file page and mark the old page 
as bad in the physical volume’s bad page list. The returned value writeErrors indicates 
whether or not errors were encountered while replacing the file page. This operation 
always allocates a single new page even if writeErrors is returned as true. 
ReplaceBadPage is subject to the same error conditions as RewritePage 


An orphan page may be read by the operation 
Scavenger.ReadOrphanPage: procedure [ 

volume: Volume.lD, id: Scavenger.OrphanHandle, destination: Space.PageNumber] 
returns [file: Fiie.File, type: File.Type, pageNumber: Fiie.PageNumber, 
readErrors: boolean]; 

Scavenger.ErrorType: type ■ {..orphanNotFound,.. 

The contents of virtual memory page destination are overwritten by the contents of the 
orphan page designated by id. The destination page must be mapped and writable or an 
address fault or write protect fault will occur. This operation returns the information that 
Pilot knows about id. The file to which it appears to belong is given by file, the apparent 
page number within that file by pageNumber, and the type of file by type. If errors were 
encountered in reading the orphan page, readErrors is returned true and the returned 
data is not guaranteed to be accurate. 

Caution: There is no validity checking to ensure that the page referred to by id is actually 
an orphan. It is the client's responsibility to pass only a currently valid OrphanHandle. 

If id does not refer to a valid page on volume, ErrorforphanNotFound] is returned. If the 
target disk is not ready, Error[diskNotReady] is raised. If the target disk reports a drive- 
level hardware failure, Error[diskHardwareError] is raised. 


Once the client is through with an orphan page, it should be deleted by the operation 

Scavenger.DeleteOrphanPage: procedure [volume: volume.lD, id: Scavenger.OrphanHandle]; 

The specified orphan page is deleted, making invalid all outstanding references to it. If 
the page is usable, it will be returned to volume’s free page pool. If the page is 
incorrigible, it will be added to the bad page list for the physical volume containing 
volume. If id does not refer to a valid page on volume, Error[orphanNotFound] is raised. 

Caution: There is no validity checking to ensure that the page referred to by id is actually 
an orphan. It is the client's responsibility to pass only currently valid OrphanHandles. In 
particular, it is possible for a client to delete a random page from a random file by 
supplying a random, but valid, value for id. 
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4.5 Virtual memory management 
Space: definitions. .. 

SpaceUsage: definitions ... 

The Mesa Processor provides a large, linearly addressed, word-organized virtual memory 
common to all PROCESSes and devices. All software, including Pilot, common software, and 
applications, resides in this single, uniformly-addressable resource. Pilot both manages 
and implements it using the system element's physical resources. In particular, client 
programs can associate areas of virtual memory with portions of files and manage system 
performance and reliability by controlling swapping between virtual and real memory. 

4.5.1 Fundamental concepts of virtual memory 

The Mesa Processor virtual memory is organized as a sequence of 2‘ 24 pages, each 
containing EnvIronment.wordsPerPage words. Pages are numbered starting from zero. 
Clients can use one fewer page than provided by the Mesa Processor because the last page 
is reserved for system use. A specific implementation of the processor may provide a 
smaller virtual address space, which does not require redefining the maximum page 
number but is accounted for in Pilot's internal data structures. A client program can 
determine the size of its virtual address space, as described in §4.5.6.1 below. 

Environment. wordsPerPage: cardinal a 256; 

Environment.PageNumber: TYPE s long cardinal; ~[0..2 24 -7) 

Environment.firstPageNumber: Environment.PageNumber = 0; 

Environment. lastPageNumber: Environment.PageNumber a 16777214; -2 24 -2 

Note: Because long subrange types are not implemented in the current version of Mesa, 
the current version of Pilot defines PageNumber as a LONG cardinal and defines the 
constants firstPageNumber and lastPageNumber to specify FiRSTfPageNumber] and 
LAST[PageNumber]. Similarly for PageCount and PageOffset below. 

Environment.PageCOUnt: TYPE a LONG CARDINAL; --[0..2 24 -1] 

Environment.firstPageCOUnt: Environment.PageCOUnt a 0; 

Environment.lastPageCount: Environment.PageCount a lastPageNumber + 1; - 2 24 -1 
Environment.PageOffset: TYPE a Environment.PageNumber; 

Environment.firStPageOffset: Environment.PageOffset = 0; 

Environment.lastPageOffset: Environment.PageOffset a lastPageNumber; 

The following operation returns a LONG pointer to the first word of a page. 

Environment.LongPointerFromPage: procedure [page: Environment.PageNumber] 

RETURNS [LONG POINTER] = INLINE 
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The following operation returns the number of the page containing pointer. If pointer is 
nil, the value returned is undefined-no signal is raised. 

Environment.PageFromLongPointer: procedure [pointer: long pointer] 

RETURNS [Environment. PageNumber] = INLINE...; 

For convenience, copies of the types wordsPerPage, PageNumber, PageCount, and 
PageOffset, and the procedures LongPointerFromPage and PageFromLongPointer are 
available in the Space interface. 

Space. wordsPerPage: cardinal = Environment. wordsPerPage; 

Space.PageNumber: type = Environment.PageNumber; 
space.PageCount: type « Environment. PageCount; 

Space.PageOffset: TYPE a Environment. PageOffset; 

Space. LongPointerFromPage: procedure [page: Environment.PageNumber] 

RETURNS [LONG POINTER] a INLINE 

Space.PageFromLongPointer: procedure [pointer: long pointer] 

RETURNS [Environment.PageNumber] = INLINE 

A basic concept used to describe parts of virtual memory is the Interval. 

Space. Interval: type ■ record [pointer: long pointer, count: Environment .PageCou nt]; 

space.nulllnterval: Space.lnterval = [pointer: nil, count: 0]; 

An Interval is a sequence of pages in the virtual address space, and is described by a 
pointer to the first page and a count of the number of pages. When Pilot returns an Interval 
to the client, the pointer points to the first word of the first page of the Interval. When 
Intervals are passed to Pilot, the pointer may point to any word in the first page. Clients 
should be careful not to misconstrue the pointer passed to Pilot as defining the first 
address affected by an operation; Space operations always start at page boundaries, 
nulllnterval may be used to denote the absence of an interval. It is returned by a few space 
operations. 

Pilot implements virtual memory using the resources of real memory and files. In 
particular, any part of virtual memory which contains information must be associated 
with backing storage consisting of a sequence of pages from some file. This sequence of file 
pages is called a window . The act of associating an area of virtual memory with a window 
is known as mapping ; the resulting interval is called a map unit. Any attempt by a 
program to reference or store into a virtual memory location which is not contained in a 
mapped interval causes an address fault . Any attempt by a program to store into a virtual 
memory location which has read-only access causes a write protect fault . Both faults cause 
the debugger to be called with an appropriate message. 

When an interval is mapped, it is typically subdivided into modest-sized swap units to 
allow more efficient management of swapping. When a PROCESS references a page not 
present in real memory, Pilot reads in the page and any adjacent swapped-out pages of the 
containing swap unit. Thus the size of a swap unit limits how many pages will be swapped 
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in when one of its pages is referenced. When inactive pages are moved from real memory 
to backing storage, Pilot ignores swap unit boundaries. That is, it will swap out a run of 
consecutive inactive pages even if the run crosses one or more swap unit boundaries. As 
described below, some attributes of mapped intervals are maintained as properties of the 
individual swap units. 

Note: In unusual circumstances (described below), Pilot may break a client-specified swap 
unit into smaller swap units. 

When an interval is mapped, its swap units are given initial access permissions. 

space .Access: type a {readWrite, readonly}; 

Each swap unit has its own Access status. readWrite specifies that clients are allowed to 
read and write in the swap units, readonly specifies that only reading is allowed. Any 
attempt to write into a page of a swap unit which is readonly results in a write protect 
fault. Operations are also provided for changing the access of existing swap units. 

When an interval is mapped, its swap units are given an initial life . This specifies whether 
or not the initial contents of the backing file are useful. 

Space.Life: type a {alive, dead}; 

Each swap unit has its own Life status, alive specifies that a swap unit initially contains 
useful data; dead specifies that it does not. Pilot uses this information to avoid reading 
pages of the interval from backing storage and writing pages containing no useful data. 
When a swap unit is marked dead, the contents of each page will be unpredictable until 
that page is written into by the client. Until that time, the client can make no assumption 
about the contents of the pages or their consistency with the corresponding pages of the 
window. Pilot insists that readonly swap units be alive; any attempt to make a readonly 
swap unit be dead will be ignored-it will remain alive. A swap unit becomes alive when 
(1) one of its pages has been written into, or (2) it is made readonly. A page can be 
swapped out either explicitly by the client or implicitly by Pilot in managing memory. The 
operation Space. Kill is provided to make existing swap units dead. 

Any Space operation may raise the signal: 

Space. Error: error [type: Space. ErrorType]; 

Space. ErrorType: type a { ... }; 

Specific values of ErrorType are defined below. In addition, some operations may raise 
other signals as defined below. 

If any Space operation is given an Interval whose pages are not completely contained 
within the implemented virtual memory of the system element, 

space.ErrorfpointerPastEndOfVirtualMemory] is raised. 

space.ErrorType: type a {..., pointerPastEndOfVirtualMemory,... }; 
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Any Space operation that transfers data to backing storage may encounter an 
unrecoverable error in reading or writing the data. If so, it will raise the signal 

Space.iOError: error [page: Environment.PageNumber]; 

page is the first page of the data being transferred which is in error. 


4.5*2 Mapping files to virtual memory intervals 

As described above, Pilot implements virtual memory by associating intervals of memory 
with backing storage consisting of a sequence of pages from some file. This sequence of file 
pages is called a window. Associating an area of virtual memory with a window is known 
as mapping ; the resulting interval is called a map unit. Virtual memory is normally 
allocated when an interval is mapped. 

A Window is a contiguous group of pages in a file starting at a specified base. 

Space.window: TYPE a RECORD [ 
file: File.File, 
base: Fiie.PageNumber, 
count: Environment. PageCount]; 

The window within the file starts at base, the first page relative to the beginning of the 
file, and extends for count pages or to the end of the file, whichever comes first. The actual 
window length is the lesser of count and the file size minus base. If count is set to 
Environment. lastPageCount, the window will extend to the end of the file. 

When an interval is mapped, it is typically subdivided into modest-sized swap units to 
allow more efficient management of swapping. If there is no known grouping of the 
references to the pages of a map unit, uniform-sized swap units should be specified; this is 
the default. If there is no knowledge of the proper size for the uniform swap unit size, the 
client may request a default swap unit size. If there is some known grouping of the 
references to the pages of a map unit, the map unit may be subdivided into swap units 
with specific sizes and locations. In some circumstances, Pilot may break a client-specified 
swap unit into smaller swap units. 


Mapped Virtual Memory 


map unit 




memory pages 

i i iflfpi , i 


file pages 

window 



i i 


file . 

-:- l 


System performance can be severely degraded if a swap unit is a substantial fraction of 
the size of real memory. Clients should ensure that map units are divided into swap units 
of manageable size. As a general rule, a swap unit should not exceed one-tenth the size of 
real memory. 
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The operations for controlling the allocation of intervals and mapping them to windows 

are Map, ScratchMap, and Unmap. 

Space.Map: PROCEDURE [ 
window: space.Window, 
usage: space.Usage «-space.unknownUsage, 
class: Space.Class <— file, 
access: Space. Access «- read Write, 
life: Space.Life «-alive, 

swapUnits: Space.SwapUnitOption *- Space. defaultSwapUnitOption] 
returns [mapUnit: Space. Interval]; 

Space.Usage: type = [0..2048); 

space.unknownUsage: Space.Usage * 0; 

Space. Class: TYPE ■ MACHINE DEPENDENT{ 

unknown(O), code(1), globalFrame(2), localFrame(3), 
zone(4), file(5), data(6), spareA(7), spareB(8), pilotResident(31)}; 

Space.SwapUnitOption: TYPE * record [ 

body: select swapUnitType: space. SwapUnitType from 
unitary a > null, 

uniform a > [size: Space. SwapUnitSize Space. defaultSwapUnitSize], 
irregular a > [ 

sizes: long descriptor for array [0..0) OF Space. SwapUnitSize] 
endcase]; 

space.SwapUnitType: type a {unitary, uniform, irregular}; 

Space.defaultSwapUnitOption: Space.SwapUnitOption a 
[uniform[space.defaultSwapUnitSize]]; 

Space.SwapUnitSize: type a cardinal; 

space.defaultSwapUnitSize: Space.SwapUnitSize a 0; 

Space. ErrorType: TYPE a { 

... incompleteSwapUnits, invalidSwapUnitSize, invalidWindow, noWindow,... }; 
Space.lnsufficientSpace: error [available: Environment.PageCount]; 

Map allocates an interval of virtual memory and associates it with a window of a file. The 
allocated interval is called a map unit. The window is then the backing store for the map 
unit. The length of the map unit is the actual window length, which is the lesser of 
window.count and the size of the file minus window.base. The allocated map unit is 
returned. 

Caution: Clients must not delete the backing storage for any mapped interval or close the 
volume containing it. The behavior of Pilot in such circumstances is undefined. 
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Caution:* Clients should ensure that different map units are not mapped to overlapping 
windows of a file if any of them is writable. The contents of the windows and the map units 
in such circumstances are unpredictable. 

If window.file is File.nullFile, then window.volume, window.base, life, and access are 
ignored and Pilot supplies anonymous backing file storage for the interval. Such a window 
is called a data window (a window mapped to a file is called a file window). The length of 
the allocated window and map unit is window.count. The interval is mapped with access 
* readWrite and life = dead. Backing storage for data windows is allocated on the system 
volume. Information in data windows is discarded when the client Unmaps the interval or, 
if the system crashes, when the system volume is next opened for writing. For UtilityPilot- 
based systems, data windows are backed only by resident memory. 

Map may encounter various conditions which will cause errors to be raised: 

Condition ERROR 

Actual window length is 0 Space. ErrorfnoWindow] 

Not enough contiguous free virtual memory Spaced nsuff icientSpace 
window.base > File.lastPageNumber Space.Error[invalidWindow] 

Volume can't be located volume.Unknown 

Volume partially online volume.NotOnline 

Volume online and closed Volume.NotOpen 

File does not exist on the volume File.Unknown 

Any of the pages of window do not exist File.MissingPages 

Cannot supply backing file for a data window volume.lnsufficientSpace 
Volume is read-only, but access = readWrite volume.ReadOnly 

Note that Space.lnsufficientSpace passes back the maximum amount that could have been 
allocated. 

The interval is mapped with the access given. If access = readonly, life is ignored and the 
interval is mapped with life * alive. If access = readWrite but window.volume is read¬ 
only, Volume.ReadOnly is raised. 

usage identifies the data in the map unit. The usage of map units will be available to the 
debugger and performance monitoring tools. The interface SpaceUsage defines subranges 
of Space.Usage for various clients and applications. Clients are encouraged to have their 
own private definitions file which further suballocates the Space. Usages assigned to them 
by the SpaceUsage interface. 

class indicates the class of the data in the map unit. Pilot uses this data in its swapping 
decisions. Clients will normally specify only file for file windows and data for data 
windows. 

If swapUnits.swapUnitType = uniform, the map unit is subdivided into equal-sized swap 
units of the indicated size. If size equals defaultSwapUnitSize or 0, Pilot will choose an 
appropriate size. If size equals or exceeds the size of the map unit, the swap unit serves no 
purpose; in this case specifying unitary swap units is more efficient. 

If swapUnits.swapUnitType = irregular, the map unit is subdivided into irregular-sized 
swap units of the sizes given in swapUnits.sizes. Each element of swapUnits.sizes is the 
size of the corresponding swap unit. If the size of any irregular swap unit is greater than 
an implementation-dependent upper limit, it will be subdivided into smaller swap units. 
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Excess elements of swapllnits.sizes are ignored. If the window does not completely cover 
the last swap unit, this swap unit will be shorter than requested. If any required element 
ofswapUnits.sizes is 0, Space. Error[invalidSwapUnitSize] is raised. If any required element 
of swapllnits.sizes is unmapped storage, an address fault will result. If the sum of the 
elements of swapllnits.sizes is less than the size of the map unit, 
space. ErrorfincompleteSwapUnits] is raised. 

If swapllnits.swapUnitType = unitary, the map unit is not subdivided into smaller swap 
units. This indicates the client’s desire to have the map unit swap as a single entity. 

ScratchMap is a more convenient way than Map to allocate temporary storage. 

Space. ScratchMap: procedure [ 

count: PageCount, usage: space. Usage «- space. unknownUsage] 
returns [pointer: long pointer]; 

The operation 

space. Unmap: procedure [ 

pointer: long pointer, returnWait: Space. ReturnWait wait] 
returns [nil: long pointer]; 

space.ReturnWait: type = {return, wait}; 

space.ErrorType: type a { ... , notMapped,... }; 

removes the association between the map unit containing pointer and the map unit’s 
window. This frees the map unit’s virtual memory for other uses. If returnWait = wait, 
the operation does not return until the contents of the window reflect the contents of the 
interval. If returnWait = return, the operation returns immediately without waiting for 
any required output to complete. Pilot ensures, however, that client actions on the backing 
window have the same effect as if returnWait = wait had been specified. If the interval is 
mapped to a data window, the information in the window is discarded. If pointer is not 
contained in a map unit, Space. Error[notMapped] is raised. If the data-in the interval 
cannot be written to the window, Space. lOError is raised. 

Note: For the current release returnWait = return is equivalent to returnWait = wait. 

Of course, pointers into a map unit should not be retained after unmapping. To encourage 
this, Unmap returns a nil pointer. The intended usage is 

myPointer Space. Unmap[myPointer]; 

References to an interval formerly occupied by the map unit can result in an address fault, 
or worse, may access or overwrite other data if the virtual memory is reused. 


4.5,3 Explicitly reading and writing virtual memory 

Copyln and CopyOut are similar to read and write operations in a conventional file 
system. However, since the interval involved must already be mapped to a backing file, 
each can also be thought of as a file-to-file copy. Neither operation returns until the data 
has been transferred and neither changes the mapping of the interval. 
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The operation 

Space.Copyln: procedure [pointer: long pointer, window: Space.Window] 

RETURNS [cOuntRead: Environment.PageCount]; 

space.ErrorType: type = { ..., readonly,... 

reads the contents of window into virtual memory starting at the page that contains 
pointer. countRead is the amount read, which is the lesser of window.count and the size 
of the file minus window.base. All virtual memory pages into which data will be read 
must be mapped. The contents of window are not changed by this operation. 

Note: The virtual memory modified may start before pointer f since reading starts at the 
first word of the page containing pointer. 

Caution: Clients should not Copy In from any part of a window currently mapped in 
virtual memory with write access. The data read in such circumstances is unpredictable. 

If any portion of the virtual memory involved is read-only, Space.Error[readOnly] is raised. 
If any portion of the virtual memory involved is unmapped, Space.Error[notMapped] is 
raised. If the data cannot be read from the window, Space.lOError is raised. In all of these 
cases, the pages preceding the offending page may have been overwritten by the 
corresponding portion of window. See also the list of errors raised by both Copyln and 
CopyOut, below. 

The operation 

Space.CopyOut: procedure [pointer: long pointer, window: Space.Window] 
returns [countWritten: Environment.PageCount]; 

writes the current contents of virtual memory, starting at the page that contains pointer, 
out to window. countWritten is the amount written, which is the lesser of window.count 
and the size of the file minus window.base. All of the virtual memory pages from which 
data will be read must be mapped. The contents of virtual memory are not changed by this 
operation. 

Note: The virtual memory being read may start before pointer f since reading starts at a 
page boundary. 

Caution: Clients should not CopyOut to any part of a window which is currently mapped 
in virtual memory. The contents of those map units in such circumstances is 
unpredictable. 

If any portion of the virtual memory involved is unmapped, Space.Error[notMapped] is 
raised. If the data in the interval cannot be read from backing storage or if it can not be 
written to the given window, Space.lOError is raised. In both of these cases, the pages of the 
window corresponding to those preceeding the offending virtual memory page may have 
been overwritten by the corresponding portion of virtual memory. If window.volume is 
read-only, Volume. Readonly is raised. 

Copyln and CopyOut both raise the following exceptions: If window.base > 
File.lastPageNumber, Space.Errorfin valid Window] is raised. If the volume cannot be 
located, Volume. Unknown is raised. Volume. NotOnline is raised if any part of the volume is 
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not online. If the volume is closed, Volume. NotOpen is raised. If the file does not exist on 
the volume, File.Unknown is raised. If any of the required pages of window do not exist, 
File.MissingPages is raised. 

4.5.4 Swapping 

Before a virtual memory location can be accessed, the page containing that location must 
be in real memory. If it is not, Pilot must read the contents of that page from its window 
into a real-memory page. If there is no available real memory page, Pilot makes room by 
writing pages to their backing window(s). Since Pilot keeps track of which pages match 
the contents of their window, it need not write unchanged pages. 

There are two ways in Pilot to cause swapping: demand swapping, and controlled 
swapping. 

4.5.4.1 Demand swapping 

When a PROCESS attempts to reference a virtual page not currently in real memory, it 
causes a page fault . When a page fault occurs, execution of that PROCESS is suspended. Pilot 
reads in the page referenced and any adjoining swapped-out pages of the containing swap 
unit. This is known as demand swapping. The suspended PROCESS is blocked until the read 
operation is complete. Of course, any other ready PROCESSes are allowed to proceed 
concurrently with the handling of the page fault. 

4.5.4.2 Controlled swapping 

Pilot also swaps in response to advice given by the client indicating its intentions with 
respect to particular intervals. The operations provided allow the client to advise Pilot 
about: 

an interval that will be referenced soon; 

a recently referenced interval that will not be referenced for a while; 

an interval whose current contents are not wanted anymore (i.e. will be written 
before being read); 

This advice enables Pilot to manage memory better than with simple demand 
swapping. 

An operation is also provided to assure that the current contents of an interval are 
accurately reflected in its backing window. This is useful for transactional systems. 

The operations Activate, Deactivate, and Kill allow the client to advise Pilot so it can 
manage swapping better. ForceOut allows the client to assure that the information in an 
interval will survive a system crash. Each of these operations can be applied to any 
interval of virtual memory, independent of map unit boundaries. The operations apply 
only to mapped portions of the specified interval, ignoring unmapped regions. 

space.Activate: procedure [interval: Space.lnterval]; 

space.Deactivate: procedure [interval: space.lnterval]; 
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Activate indicates to Pilot that the interval is expected to be referenced in the near future 
and that Pilot should begin reading it in. This operation returns without waiting for any 
input to complete. Deactivate indicates to Pilot that the interval is not likely to be 
referenced soon, and that Pilot should write it out and release the real memory allocated to 
it. This operation also returns without waiting for any output to complete. 

The following procedures allow the activation and deactivation of swap units containing 
Mesa code. 

Space.ActivateProc: procedure [proc: -generic- procedure]; 
space.DeactivateProc: procedure [proc: -generic- procedure]; 
space.ErrorType: type * { ... # invalidProcedure,... }; 

ActivateProc causes the swap unit (code pack) containing the code for the procedure proc 
to be activated, and DeactivateProc deactivates it. If proc has arguments or results, 
normal usage is ActivateProc[iOOPHOLE[proc, procedure]]. If proc is not a valid procedure, 
space.Error[invalidProcedure] is raised. 

A common technique for using ActivateProc and DeactivateProc is to package a vacuous 
procedure with the code of interest. This procedure serves as a "handle” on a code pack, 
decoupling the function implemented by the code pack and the explicit procedures which 
compose it. 

The operation 

Space. Kill: procedure [interval: Space. Interval]; 

asserts to Pilot that the current contents of the interval are of no further value. Kill is 
intended to be used two ways: to avoid reading a page about to be overwritten, and to avoid 
writing a page which is no longer useful. 

Pilot uses this information to avoid input/output activity on the interval. When Kill is 
applied to an interval, any real memory in the interval is immediately reclaimed; 
furthermore, any writable swap units wholly contained in the interval are marked dead. 
Pilot may supply arbitrary values for the contents of any page of a dead swap unit until 
the page is next written into by the client. The client should not make any assumptions 
about the contents of these pages or their consistency with the corresponding pages of the 
window (see also the previous discussion of the Life attribute). 

The operation 

Space.ForceOut: procedure [interval: Space. Interval]; 

causes the window(s) of the interval to agree with the current contents of virtual memory. 
It does not return until all required writing is complete. Any pages of the interval in real 
memory will remain there. Since Pilot keeps track of which pages match the contents of 
their window, ForceOut can bypass writing unchanged pages. If the data in the interval 
can not be written to the given window, Space. lOError is raised. If ForceOut causes any 
pages to be written to backing storage, the swap units containing those pages will be 
marked alive. 
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Any temporary disagreement between an interval and its window should be invisible 
during normal operation of the system. The intended use of ForceOut is to guarantee that 
the information in an interval will survive a system crash, by forcing it out to a non¬ 
volatile backing storage. . 

Calls on Activate and Deactivate may be added or deleted anywhere in a program without 
affecting its correctness. Calls on Kill may be deleted from, but not necessarily added to, a 
program without affecting its correctness. Calls on ForceOut may be added to, but not 
necessarily deleted from, a program without affecting its correctness. 

4.5.5 Access control 

The following operations allow portions of virtual memory to be made read-only or read- 
write. 

space.SetAccess: procedure [interval: Space. Interval, access: Space. Access]; 

This operation makes all swap units which include any portion of interval to be readonly 
or readWrite. If the swap units were made readonly, subsequent attempts to store into a 
page of any of these swap units will cause a write protect fault. If access = readWrite but 
the volume to which the interval is mapped is read-only, Volume. Readonly is raised. 

When an interval is made readonly, Pilot also does a ForceOut on the swap units and 
marks them alive. While doing this, if the data in the interval cannot be written to its 
window, Space.lOError is raised; in this case, the swap units preceding the offending page 
may have been made readonly and alive. 

If an arbitrary interval within a map unit is given, this operation may affect less virtual 
memory than that implied by the client-specified swap unit structure; this is because Pilot 
may occasionally break a client-specified swap unit into smaller swap units. A client can 
precisely specify which swap units are affected by having interval begin and end on the 
boundaries of the client-specified swap units. 

Note: The virtual memory affected may start before interval.pointer f since this 
operation starts at the first page of the swap unit containing interval.pointer f . Similarly, 
the virtual memory affected may extend past (interval.pointer + count * 
wordsPerPage) f. 

Two convenience operations are also provided. 

Space.MakeReadOnly: procedure [interval: Space.lnterval] = 
inline { space.SetAccess[interval, readonly] }; 

Space.MakeWritable: procedure [interval: space.lnterval] * 
inline { space.SetAccess[interval, readWrite] }; 

4.5.6 Explicit allocation of virtual memory and special intervals 

Virtual memory is normally allocated when a window is mapped. However, facilities are 
also provided to allocate virtual memory explicitly, independent of the act of mapping. 
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4.5*6,1 Special intervals of virtual memory, main data spaces, and pointers 

When virtual memory is being explicitly allocated, some intervals are of special interest: 

Space.virtualMemory: readonly Space.Interval; 

virtualMemory describes the entirety of the virtual memory address space as actually 
implemented on the system element on which Pilot is running. The actual size of the 
virtual memory of a particular system element is given by virtualMemory.count. 

A special kind of interval which is recognized by the Mesa processor and by Pilot is the 
Main Data Space (MDS). This interval consists of 256 pages (2 16 words) and holds the Mesa 
run-time data structures needed to support the execution of a collection of PROCESSes. 
Every PROCESS is associated with some md$. The procedure 

Space. MDS: PROCEDURE RETURNS [space.lnterval] ; 

returns the interval of the MDS of the PROCESS calling it. One MDS may be shared by many 
PROCESSes. A PROCESS may allocate virtual memory either inside or outside of its own MDS. 
Information within the MDS can be accessed by a POINTER, which is interpreted relative to 
the beginning of the MDS. Information outside of the MDS is accessed by a long pointer or a 
POINTER RELATIVE to a long BASE pointer. Since space in the MDS is typically in short supply, 
clients should normally allocate virtual memory outside the MDS. Executable code is not 
contained within any MDS and is shared by all PROCESSes in all mds's. 

Note: Although the Mesa Processor allows multiple mds's, only a single mds is 
implemented by the current version of Pilot. 

4.S.6.2 Explicit allocation of virtual memory 

Operations are provided for the explicit allocation and deallocation of an interval of 
virtual memory independent of the act of mapping. 

Space.Allocate: PROCEDURE [ 

count: Environment.PageCount, within: Space.lntervalSpace.virtualMemory, 
base: Environment.PageOffset «-Space.defaultBase] 
returns [interval: Space.lnterval]; 

Space.defaultBase: Environment.PageOffset as ...; 

Space. ErrorType: type as {..., alreadyAllocated, invalidParameters,... }; 

This operation allocates an interval of unmapped virtual memory within an arbitrary 
containing interval. If count is zero, space. ErrorfinvalidParameters] is raised. 

Managing an allocated interval is the responsibility of the client. Part or all of the interval 
may used for mapping windows using Space. MapAt. 

The client may either specify exactly the location of the interval to be allocated or have 
Pilot choose a suitable interval. To have Pilot choose a suitable starting location within 
the containing interval, the client passes defaultBase. If there are not enough contiguous 
unallocated pages in within, Space. InsufficientSpace is raised; this signal passes the 


4-40 




File Storage and Memory 


4 


maximum amount that could have been allocated. To specify the location of the interval 
exactly, the client gives a base other than defaultBase. The interval to be allocated will 
start at the specified offset base from the start of the containing interval. If the requested 
interval would overlap an already allocated interval, Space. Error[alreadyAllocated] is 
raised. If the end of the interval would exceed the end of the containing interval, 
space.Error[invalidParameters] is raised. 

Note: When Pilot chooses the location of the interval, any special properly-contained 
subintervals of within (e.g. t the MDS) may be skipped over. Thus Pilot may raise 
Space. InsufficientSpace when within = Space. virtualMemory even though there is still 
space available in the mds. 

The operation 

Space.Deallocate: procedure [interval: Space. Interval]; 

Space.ErrorType: type = { ..., notAllocated, stillMapped,... }; 

deallocates the interval, making it available for other uses, interval should only contain 
virtual memory obtained from Space. Allocate or Space. UnmapAt. If any portion of the 
interval is mapped, Space. ErrorfstillMapped] is raised. If any portion of the interval is 
already deallocated, Space. Error[alreadyDeallocated] is raised. If interval exceeds the 
limits of implemented virtual memory, Space. Error[invalidParameters] is raised. 

4.S.6.3 Mapping explicitly allocated virtual memory to files 

The operations for controlling the mapping of explicitly allocated intervals are MapAt and 
UnmapAt. 

Space.MapAt: PROCEDURE [ 
at: Space.lnterval, 
window: Space.Window, 
usage: Space.Usage«- Space.unknownUsage, 
class: Space.Class file, 

access: space.Access readWrite, 
life: Space.Life alive, 

swapUnits: Space.SwapUnitOption <--Space.defaultSwapUnitOption] 
returns [mapUnit: space.lnterval]; 

This operation maps a window of a file to virtual memory starting at at.pointer. The 
interval at must have been previously obtained from Allocate or UnmapAt or be a 
subinterval of one. The resulting interval is a map unit. The length of the map unit is the 
actual window length. If at contains any unallocated pages, Space. Error[notAllocated] is 
raised. If the end of the map unit would exceed the end of at, 
Space. ErrorfinvalidParameters] is raised. This operation is otherwise analagous to 
Space. Map ( q.v .). 
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The operation 

Space. UnmapAt: procedure [ 

pointer: long pointer, returnWait: Space.ReturnWait wait] 
returns [interval: space.Interval]; 

removes the association between the map unit which contains pointer and its window, 
interval describes the map unit being unmapped. If the virtual memory of the map unit 
was originally obtained from Allocate, the associated interval remains the property of the 
client. If the virtual memory of the map unit was originally obtained from Map, the client 
acquires the associated interval. The client retains this interval until it is Deallocated. 
This operation is otherwise identical to Space. Unmap (q.u.). Note that a client can Unmap 
an interval originally obtained from Allocate and subsequently mapped with MapAt; the 
associated interval becomes the property of Pilot. 

4.5.7 Map unit and swap unit attributes, utility operations 
The operation 

Space.GetMapUnitAttributes: procedure [pointer: long pointer] 
returns [mapUnit: space.lnterval, window: space.Window, 
usage: Space.Usage, class: Space.Class, swapUnits: Space.SwapUnitOption]; 

returns the location and length of the map unit which contains pointer, the window to 
which it is mapped, the usage of the map unit, its swapping class, and the swap unit 
structure. If the map unit is mapped to a data window, the returned window will be 
[[File.nulliD, Volume. nulllD], 0, count], window.count (which equals the returned 
interval.count) reflects the actual size of the map unit. It may be less than the 
window.count given to Map or MapAt if the file was not long enough to supply the 
requested count. If swapUnits.swapUnitType a uniform, the returned swapUnits.size is 
the actual size of the swap units; defaultSwapUnitSize is never returned. If 
swapUnits.swapUnitType = irregular, the returned swapUnits.sizes is nil; 
GetSwapUnitAttributes may be used to discover the sizes of irregular swap units. If 
pointer is not in any map unit, this operation returns mapUnit = Space. nulllnterval and 
window.count * 0. Thus a pointer p points to unmapped storage if 

GetMapUnitAttributes[p].mapUnit.count ■ 0. If the map unit containing pointer was 
mapped by some facility other than Space, Space. Error[invalidParameters] is raised. 

The operation 

Space.GetSwapUnitAttributes: procedure [pointer: long pointer] 

returns [swapUnit: space.lnterval, access: space.Access, life: space.Life]; 

returns the location, length, current access, and current life of the swap unit which 
contains pointer. The returned count reflects the actual size of the swap unit. In the case of 
uniform or irregular swap units, the size will differ from the size given to Map or MapAt if 
the requested size was zero or larger than Pilot implements. Also, Pilot may occasionally 
break a client-specified swap unit into smaller swap units. If pointer is not in any swap 
unit, this operation returns interval = Space. nulllnterval. 
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The following operation returns the number of pages required to contain a specified 
number of words. 

Space.PagesFromWords: procedure [wordCount: long cardinal] 

RETURNS [pageCount: Environment.PageCount] as; 

The operation 

Space.Pointer: procedure [pointer: long pointer] returns [pointer]; 

converts a long pointer to an equivalent pointer. If the argument is not in the mds of the 
calling process, Space. ErrorfinvalidParameters] is raised. 

The operation 

Space. PointerFromPage: procedure [page: Environment.PageNumber] returns [pointer]; 

returns a POINTER which points to the first word of the argument page. If the argument is 
not in the mds of the calling process, Space. Error[invalidParameters] is raised. 

4.6 Pilot memory management 

Four different facilities are available for acquiring and managing storage areas. Global 
frame space is considered a precious resource, but may be used for small (a few dozen 
words) storage that needs to be shared by multiple procedures and processes. Local 
frames, existing only as long as it's procedure instance, may be used for storage items that 
are less than a few hundred words in length and are not shared among procedures and 
processes. The Space machinery, described in detail in §4.5, provides contiguous groups of 
pages (256 word blocks) in the virtual memory and is most suitable for obtaining large 
blocks of storage. There is also a Pilot free storage package for managing arbitrarily sized 
nodes within client-designated areas of virtual memory called zones. 

All state information pertaining to a zone is recorded within the zone itself, and, as a 
consequence, each zone can be managed independently of all others through the same 
interface, Zone. The Heap facility provides further assistance in managing arbitrary sized 
nodes. The following properties distinguish a heap from a zone: 

1. Heaps are more automatic, occupying system-designated (rather than client- 
designated) virtual memory, and expanding automatically (rather than requiring a 
client call). 

2. Heaps are designed to support the Mesa language facilities for dynamic storage 
allocation (uncounted zones, new, free). 

3. Some care is taken to treat large nodes ( e.g ., larger than 128 words) efficiently. 

4. There is no mechanism to file away a heap and recreate it later. 

It is expected that most Pilot clients will want to use the heap facilities. The zone facilities 
provide extra fine-grain control which may be useful for certain critical applications. Like 
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the zone facility, the heap performs best when the sizes of nodes are small compared to the 
size of the entire heap. 


4.6.1 Zones 

Zone: definitions 

The Pilot zone management facility is based upon a suggestion by Don Knuth (The Art of 
Computer Programming , Volume 1, p. 453, #19). Within a zone, free nodes are kept as a 
linked list. One hidden word containing bookkeeping information is stored with each 
allocated node, and additional bookkeeping information is kept in the header of each zone. 
Allocation and release of nodes are usually very fast. Adjacent free nodes are always able 
to be coalesced. It is also possible to add new areas of virtual memory to enlarge a zone. 
These new areas, called segments , are linked together so that they may be deleted if all the 
nodes in a seqment become free. In addition, an entire zone may be deleted. A zone may 
be saved in a file, and later recreated in memory at a different address. 

The zone facility performs best when the sizes of nodes are small compared to the sizes of 
the block(s) making up the zone. A typical use for a zone is, for example, for small, 
transient data structures, such as the nodes of a temporary list structure or the bodies of 
(short) strings when the maximum length must be computed dynamically or the structure 
must outlive the frame that creates it. Use of a zone for large (i.e., multi-page) nodes 
decreases flexibility in storage management and is not recommended. 

The allocator in the Pilot free storage package returns 16 bit pointers relative to a long 
base pointer supplied at the time the zone is created. Note that these values are free 
pointers (type relative pointer to unspecified) which must be cast appropriately (usually by 
assignment) before being used. Allocated nodes are not relocatable within the zone, and 
there is no garbage collection or automatic deallocation. 

Because of its use for managing private, internal zones of Pilot, the zone facility raises no 
signals or errors. Instead, the various operations return a status from the enumerated 
type: 

Zone.Status: type * {...}; 

4.6.1.1 Zone management 

A zone can be created from a block of client supplied virtual memory by calling the 
procedure Create. 

zone.Create: procedure [ 

storage: long pointer, length: zone.BlockSize, zoneBase: Zone.Base, 
threshold: zone.BlockSize <-zone.minimumNodeSize, checking: boolean false] 
returns [zH: zone.Handle, s: Zone.Status]; 

zone.BlockSize: type ■ cardinal; 

Zone. Base: TYPE a Environment. Base; 

zone.minimumNodeSize: readonly zone.BlockSize; 
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zone.Handle: type [2]; 

Zone.nullHandle: Zone.Handle ■ ...; 

zone.Status: type = { ..., okay, storageOutOfRange, zoneTooSmall,...}; 

A zone is created to occupy the number words of virtual memory specified by length and 
beginning at the word pointed to by storage. The argument zoneBase is a long base 
pointer which supplies the base address for all relative pointer calculations in this zone. 
The argument threshold indicates the minimum size node that will be maintained by this 
zone. All allocation requests will be rounded up to this size and no unallocated fragments 
smaller than this will be left in the zone. 

The argument checking indicates whether or not some internal checking of the 
consistency of the zone is turned on. The checking option is useful for helping debug client 
programs which are improperly using or freeing nodes in the zone. Because it causes each 
node to be checked on each zone operation, checking degrades performance somewhat. 

The virtual memory must be mapped and have write permission. If it does not, an address 
fault or write protection fault will be generated as if the client program had attempted to 
write directly into that area of virtual memory. If length is too small to support a zone 
with at least one node of size threshold, a status of zoneTooSmall is returned. All 
segments of a zone must lie entirely within a single 64K word address space, i.e., all of the 
zone must be addressable by 16 bit relative pointers based on base. If that is not the case, 
or if the zone size is not in the range [0..2 16 ), a status of storageOutOf Range is returned. 

Caution: In this version of Pilot, zone sizes are restricted to the range [O.^S). 

If a zone is successfully created, the Create operation returns a status of okay and a 
Zone.Handle which is used to identify the zone for all other zone operations. 

nullHandle is never the Handle to an actual zone and is provided as a reference to the null 
zone. 

A client may save a zone in a file for later use. Since the implementation of a zone may 
change from release to release, client code using filed zones must be prepared to cooperate 
in recovering from a "wrong version" condition detected by Pilot, as explained below. A 
client may request Pilot to resurrect an old zone, presumably one previously saved in a 
permanent file, with the procedure: 

zone.Recreate: procedure [storage: long pointer, zoneBase: zone.Base] 

returns [zH: zone.Handle, rootNode: zone.Base relative pointer, s: Zone.Status]; 

Zone.Status: type = {..., wrongSeal, wrongVersion}; 

The storage parameter to Recreate should point to a place in virtual memory which is 
mapped to a file window containing the contents of a zone created (or recreated) earlier in 
the same or an earlier run. While the storage and corresponding zoneBase need not 
remain fixed each time a zone is recreated, the arithmetic difference between them must 
be kept invariant. Note also that the relative positions of any segments added to the zone 
must stay invariant. 
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Normally Recreate returns a status of okay, together with an ordinary zone handle for the 
zone and the value of the root node of the zone. However it is possible that an incompatible 
implementation change in Pilot has been made since the zone was created, in which case 
Recreate returns a status of wrongVersion, an invalid zone handle, and the correct value 
of the root node of the old zone. In this case it is the client's responsibility to rebuild a new 
version of the zone , perhaps by enumerating the nodes reachable from the root node via 
fields defined within the client node format(s). Finally, a status of wrongSeal indicates a 
client programming error: the storage passed to Pilot does not begin with a fixed "seal” 
value, and probably never contained a valid zone. In this case, the returned handle and 
root node are both undefined. 

zone.GetRootNode: procedure [zH: Zone-Handle] 
returns [node: zone.Base relative pointer]; 

Zone.SetRootNode: procedure [zH: Handle, node: zone.Base relative pointer]; 

zone.nii: readonly zone.Base relative pointer; 

To support the notion of a filed zone, Pilot allows a root node to be associated with every 
zone. This value, initially set to Zone.nii, is just a short relative pointer which the client 
may use to point to a distinguished node within the zone, thus providing a "point of 
purchase" on the data structures contained within the zone. As discussed above, the 
entire set of nodes in a filed zone should be enumerable from the root (unless the entire 
data structure can be reconstructed from some other source). 

The Mesa construct nil does not apply to relative pointers such as those used to reference 
nodes. For this reason, the constant Zone.nii is provided for representing the nil relative 

pointer. 

There is no explicit operation for destroying a zone. The client program merely recovers 
the storage it had provided and ceases to use the zone. 

The following procedure returns the attributes of a zone. 

Zone.GetAttributes: procedure [zH: zone. Handle] 

returns [zoneBase: zone.Base, threshold: zone.BlockSize, 
checking: boolean, storage: long pointer, length: zone.BlockSize, 
next: zone.SegmentHandle]; 

zone.SegmentHandle: type [1]; 

zone.nullSegment: readonly zone.SegmentHandle; 

The results zoneBase, threshold, storage, and length are exactly as specified when the 
zone was created. The result checking indicates whether or not consistency checking is 
currently enabled for this zone (see below). The result next is a handle for an additional 
segment of this zone (see §4.6.1.2); Zone.nullSegment is returned if there are no additional 
segments in this zone. No validity check is made of zH, the Zone.Handle, prior to returning 
these results. 
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The following operation is used to enable or disable consistency checking of the zone. If 
checking is TRUE, a consistency check is made that all of the nodes in the zone, and the data 
structures of the zone, are well-formed. 

zone.SetChecking: procedure [zH: zone. Handle, checking: boolean] 
returns [s: Zone. Status]; 

Zone.Status: type ■ {..., invalidZone, invalidSegment, invalidNode, nodeLoop,...}; 

A status of invalidZone indicates the the basic data structures of the zone identified by zH 
are malformed. A status of invalidSegment indicates that although the primary block of 
virtual memory in the zone is okay, one of its segments (see §4.6.1.2) is malformed. A 
status of invalidNode indicates that within the zone, some node is malformed or invalid. 
This could mean that the overhead word of the node has been overwritten, that a "node’ has 
been freed which does not lie within the virtual memory constituting the zone, or that a 
Tree’ node is not properly linked on the free list in the zone. A status of nodeLoop 
indicates that the free list has a loop within it. Except as otherwise indicated, any of these 
status results can be returned if consistency checking is enabled and the corresponding 
condition is detected during the execution of any of the operations in the Zone interface. 


4.6.1.2 Segment management 

The virtual memory provided to the zone at the time it is created is the primary storage of 
the zone. It is of fixed size and cannot be reclaimed by the client so long as the zone is of 
any value. Additional blocks of storage can be added to the zone by the procedure: 

zone.AddSegment: procedure [zH: zone. Handle, storage: long pointer, 
length: zone.BlockSize] 

returns [sH: Zone.SegmentHandle,s: Zone.Status]; 

Zone.Status: type * {..., segmentTooSmall,... }; 

This operation creates a new segment of the zone containing the number of words 
indicated by length and beginning at the virtual memory word pointed to by storage. The 
virtual memory of the segment must be mapped and have write permission. If it does not, 
an address fault or write-protect condition will be generated as if the client had written or 
referenced that part of virtual memory directly. This area of virtual memory must also be 
addressable by 16 bit pointers relative to the zoneBase of the zone, and length must be in 
the range [0..216). if it is not, a status of storageOutOfRange is returned. If length does 
not specify enough virtual memory to implement a segment and to contain at least one 
node of size threshold, a status of segmentTooSmall is returned. 

Caution: In this version of Pilot, segment sizes are restricted to the range [O.^ 1 ^). 

All segments of a zone are linked together in a list pointed to by the nextSegment 
attribute of the zone. The attributes of any segment, including the next member of the list 
are returned by: 

zone.GetSegmentAttributes: procedure [zH: zone.Handle,sH: zone.SegmentHandle] 
returns [storage: long pointer, length: zone.BlockSize, next: Zone.SegmentHandle]; 


4-47 




4 


Pilot Programmer’s Manual 


A segment may be removed from a zone if it contains no allocated nodes. This is 
accomplished by the procedure: 

Zone.RemoveSegment: procedure [zH: zone. Handle, sH: Zone.SegmentHandle] 
returns [storage: long pointer, s: zone.Status]; 

Zone.Status: type * {..., nonEmptySegment,... }; 

A status of okay indicates that the segment was successfully removed. A status of 
nonEmptySegment indicates that the segment still contains allocated nodes and that 
therefore it could not be removed. A status of invalidZone or invalidSegment is returned if 
the data structures of the zone are not well-formed enough to permit removal of the 
segment. 

4.6.1.3 Node allocation and deallocation 

The operations of this section provide the facilities for allocating and deallocating nodes in 
a zone. 

Zone.MakeNode: procedure [zH: zone.Handle, n: Zone.BlockSize, 
alignment: Zone.Alignment «- al] 
returns [node: zone.Base relative pointer, s: Zone.Status]; 

Zone.Alignment: type * {al, a2, a4, a8, a16}; 

Zone.Status: type a {..., noRoomlnZone, ... }; 

MakeNode allocates a node of n words in the zone identified by zH. An optional alignment 
may be specified for this node, in which case the node is aligned in virtual memory as 
follows: 

if alignment is set to al then the node is word aligned 

if alignment is set to a2 then the node is double word aligned 

if alignment is set to a4 then the node is quad word aligned 

if alignment is set to a8 then the node is eight word aligned 

if alignment is set to a16 then the node is sixteen word aligned 

If a node of at least n words of the desired alignment can be allocated, a 16 bit pointer 
relative to the zoneBase of the zone is returned pointing to the node, along with a status of 
okay. More than the requested number of words will be allocated to avoid fragmentation 
of the free space remaining in the zone into pieces of size less than the threshold of the 
zone. If a contiguous block of space is not available in the zone, a status of noRoomlnZone 
is returned. The value Zone. nil is returned by MakeNode if it is unable to allocate a node. 

If B is the zoneBase of the zone and node is the relative pointer returned by MakeNode 
then a Mesa LONG pointer to the node is represented by the expression @B[node], If B * 
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Space. MDS[]. pointer then the expression LOOPHOLEfnode, POINTER] is a Mesa short pointer to 
the node. 

zone.FreeNode: procedure [zH: zone.Handle, p: long pointer] 

RETURNS [s: Zone.status]; 

This operation deallocates the node pointed to by p in the zone indicated by zH. If the node 
does not lie within that part of virtual memory addressable by 16 bit relative pointers 
based on the zoneBase of the zone, or the node is not marked in use, a status of 
invalidNode is returned. Otherwise, a status of okay is returned. More detailed checking, 
including that the node actually lies within the zone (or one of its segments) is only done if 
consistency checking is enabled. 

zone.SplitNode: procedure [zH: zone.Handle, p: long pointer, n: zone.BlockSize] 

RETURNS [s: Zone.status]; 

This operation splits the node pointed to by p, retaining the first n words and freeing the 
remainder. No split occurs if the remainder would be smaller than the threshold of the 
zone. 

Zone.NodeSize: procedure [p: long pointer] returns [n: zone.BlockSize]; 

This operations returns the actual size of the node pointed to by p (this may exceed the 
allocated size to avoid fragmentation). No check is made to determine the validity of the 
node. 

4.6.2 Heaps 

Heap: definitions ...; 

The heap facility consists of the Pilot interface Heap together with some language features 
built into Mesa. The operations in Heap are primarily concerned with creating and 
deleting heaps. Almost all node allocation and deallocation may be performed using Mesa 
new and free constructs, which also allow initialization and pointer management. The 
reader is assumed to be familiar with these Mesa features. 

4.6.2.1 Heap management 

There are three types of heaps: normal , uniform , and mds. Normal heaps allow allocation 
of arbitrary sized objects. Uniform heaps allow allocation of objects whose size is equal to 
or less than a fixed size. The MDS heaps allow allocation of arbitrary sized objects from 
withifi the MDS. 

Normal and uniform heaps are identified by a value of type uncounted zone, mds heaps by 
a value of type MDSZone. Pilot provides a standard normal heap and a standard mds heap: 

Heap.systemZone: readonly uncounted zone; 

Heap.systemMDSZone: readonly MDSZone; 
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Note that the readonly attribute applies not to the contents but to the reference to the 
particular heap. 

The system provided heaps can be used to share information between subsystems. If a 
subsystem requires a lot of private storage it is often more efficient to create a private 
heap than to use the system provided heaps. If objects being allocated are all the same size, 
uniform heaps are more efficient since less overhead is required for each node. To create 
additional heaps, call either Create to create a normal heap, CreateUniform to create a 
uniform heap, or CreateMDS to create an mds heap. 

Heap.Create: proc[ 

initial: Environment. PageCount, 

maxSize: Environment.PageCount«- Heap.unlimitedSize, 
increment: Environment.PageCount«- 4, 
swapUnitSize: Space.SwapUnitSize «- Space. defaultSwapUnit. 
threshold: Heap.NWords«— Heap.minimumNodeSize, 
largeNodeThreshold: Heap.NWords *— Environment.wordsPerPage/2, 
ownerchecking: boolean «- false, 
checking: boolean «- false] 

RETURNS [UNCOUNTED ZONE]; 

Heap.CreateUniform: proc[ 
initial: Environment.PageCount, 

maxSize: Environment.PageCount <— Heap.unlimitedSize, 
increment: Environment.PageCount <- 4, 

swapUnitSize: Space.SwapUnitSize«—space.defaultSwapUnit, 
objectSize: Heap.NWords, 
ownerChecking: boolean «-false, 
checking: boolean «- false] 

RETURNS [UNCOUNTED ZONE]; 

Heap.CreateMDS: proc[ 

initial: Environment.PageCount, 

maxSize: Environment.PageCount«- Heap.unlimitedSize, 
increment: Environment.PageCount«- 4, 

swapUnitSize: Space.SwapUnitSize *- Space.defaultSwapUnit, 

‘threshold: Heap.NWords <— Heap.minimumNodeSize, 
largeNodeThreshold: Heap.NWords «- Environment.wordsPerPage/2, 
ownerChecking: boolean *- false, 
checking: boolean <-false] 
returns [MDSZone]; 

Heap.NWords: TYPE ■ [0..32766); 

Heap.unlimitedSize: Environment.PageCount * ...; 

Heap.minimumNodeSize: readonly Heap.NWords; 

Heap.Error: error [type: Heap.ErrorType]; 
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Heap.ErrorType: type = {.., maxSizeExceeded, invalidParameters, invalidSize, 
insufficientSpace, otherError,.. .}; 

When an allocation request would exceed the current size of a heap, the heap is 
automatically expanded by increment pages. It is still a good idea to specify a reasonable 
value for initial to minimize fragmentation. (The expansions to a heap are not, in general, 
contiguous in virtual memory.) 

If a nondefault maxSize is specified, the signal Heap.ErrorfmaxSizeExceeded] is raised 
when a heap is being created or expanded, or a large node is being allocated, and the total 
number of pages allocated for the heap exceeds maxSize. The signal 
Heap.ErrorfinsufficientSpace] is raised when the underlying zone implementation returns 
a status to the Heap package that is either unexpected or not understood. 

If a nondefault swapUnitSize is specified, the spaces created to hold the heap and its 
extensions will have uniform swap units of size swapUnitSize. If it is defaulted, no swap 
units will be created. 

For normal or MDS heaps, the argument threshold indicates the minimum size node that 
will be maintained by this heap. All allocation requests will be rounded up to this size and 
no unallocated fragments smaller than this will be left in the heap. The argument 
largeNodeThreshold indicates the size of node which will not be allocated in the normal 
fashion. Allocation requests of this size or larger will be handled by creating a separate 
space for each, which is deleted when the node is deallocated. 

For uniform heaps, the argument objectSize indicates the size node that will be 
maintained by this heap. All allocation requests greater than this size will result in the 
signal Heap.ErrorfinvalidSize] being raised. 

If ownerchecking is true, owner checking is enabled (see the description in §4.7. 2.3 below 
of the operation CheckOwner). The argument checking indicates whether or not some 
internal checking of the consistency of the heap is turned on. 

The checking option is useful for helping debug client programs which are improperly 
using or freeing nodes in the heap. However, because it checks each node on each heap 
operation, it does degrade performance noticeably. 

A heap may be deleted with one of the operations, as appropriate: 

Heap.Delete: procedure [z: uncounted zone, checkEmpty: boolean false]; 

Heap.DeleteMDS: procedure [z: MDSZone, checkEmpty: boolean 4-false]; 

If checkEmpty is true, then Heap.Error[invalidHeap] will be raised if there are still nodes in 
the heap which have not been deallocated. 

4.6.2.2 Node allocation and deallocation 

Nodes are allocated from a heap using the Mesa new operator and are deallocated using 
the Mesa free statement. For the remainder of this section, assume that z and mz have 
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been declared as a uncounted zone and an MDSZone, respectively, and have been 
initialized. For example: 

z: uncounted zone a Heap.systemZone; 

mz: MDSZone = Heap.systemMDSZone; 

or 

z: uncounted zone = Heap.Createfinitial:...]; 
mz: MDSZone « Heap.CreateMDSfinitial:...]; 

(It is also possible to initialize z and mz by assignment subsequent to their declaration.) 

If T is a type and t is an expression of type T then 

Z.NEWfT t] 

allocates a node of size at least SIZe[T], sets its contents to t , and returns a long pointer to 
the node. Similarly for 

itiz.new[T 1 ] 

except a short pointer is returned. If p is a long pointer to T pointing to a node previously 
allocated from z then 

Z.FREE[@p]; 

sets p to nil and frees the node p had pointed to (in that order). Similarly, if mp is a pointer 
TO T pointing to a node previously allocated from mz then 

mz .free [@mp]; 

sets mp to nil and frees the node mp had pointed to (in that order). In both cases of free, if 
p is NIL then the operation is a no-op. 

A special construct is provided for allocating a string body from a heap: 

z.NEw[StringBody[n]] 

allocates a node large enough to hold a string body of n characters, initializes its length 
field to 0 and its maxlength field to n (but leaves its text field uninitialized), and returns a 
LONG STRING pointing to the node. Similarly for 

mz.NEw[StringBody[/i]] 

except a short string is returned. 
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4.6.2.3 Miscellaneous operations 

It is possible to determine the initial parameters and current statistics of a heap by calling 
the appropriate one of: 

Heap.GetAttributes: proc[z: uncounted zone] 

RETURNS[ 

heapPages, maxSize, increment: Environment.PageCount, 
swapllnitSize: Space.SwapUnitSize, 

ownerchecking, checking: boolean, attributes: Heap.Attributes]; 

Heap.Attributes: type = RECORD [ 
select tag: Type from 
normal * > [ 

largeNodePages: Environment.PageCount, 
threshold, largeNodeThreshold: Heap.NWords], 
uniform * > [objectSize: Heap.NWords], 
endcase]; 

Heap.GetAttributesMDS: proc[z: MDSZone] 

RETURNS[ 

heapPages, largeNodePages, maxSize, increment: Environment.PageCount, 
swapUnitSize: Space.SwapUnitSize, 
threshold, largeNodeThreshold: Heap.NWords, 
ownerchecking, checking: boolean]; 

If a client is about to create a large number of nodes which together would cause a heap to 
expand by more than increment (the parameter to Create) pages, some fragmentation may 
be avoided by first calling: 

Heap.Expand: procedure [z: uncounted zone, pages: Environment.PageCount]; 
Heap.ExpandMDS: procedure [z: MDSZone, pages: Environment.PageCount]; 

The client can return the heap to the state it had when it was created by calling: 

Heap.Flush: procedure [z: uncounted zone]; 

Heap.FlushMDS: procedure [z: MDSZone]; 

All nodes that were allocated are freed and all extensions to the heap are freed. 

If many nodes have been deallocated from a heap, for example at the end of some 
intermediate phase of activity, it may be possible to release some of the virtual memory 
occupied by that heap. The operations 

Heap.Prune: procedure [z: uncounted zone]; 

Heap.PruneMDS: procedure [z: MDSZone]; 
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examine each of the spaces containing expansions to the heap z, releasing any containing 
no nodes. 

If a heap was created with ownerChecking * true, then the procedures 
Heap.CheckOwner: procedure [p: long pointer, z: uncounted zone]; 

Heap.CheckOwnerMDS: procedure [p: long pointer, z: MDSZone]; 

Heap.ErrorType: type = {..., invalidOwner,... 

may be called to determine if a node was allocated by the same module (global frame) as 
the caller of CheckOwner. If not, Heap.Error[invalidOwner] will be raised. 

It may be determined whether or not ownerChecking = true by calling 

Heap.OwnerChecking: procedure [z: uncounted zone] returns [boolean]; 

Heap.OwnerCheckingMDS: procedure [z: MDSZone] returns [boolean]; 

The checking feature, described in §4.6.2.1 above, may be turned on and off by: 

Heap.SetChecking: procedure [z: uncounted zone, checking: boolean]; 

Heap.SetCheckingMDS: procedure [z: MDSZone, checking: boolean]; 

Heap.ErrorType: type = {... , invalidHeap, invalidNode, invalidZone,... 

There may be times when it is convenient to allocate untyped storage, say for a variable- 
length structure not defined as a Mesa SEQUENCE. Several procedures are provided for 
these cases. Wherever possible it is preferable to use NEW and FREE instead, redefining 
types in terms of SEQUENCE where necessary. The following two procedures allocate a node 
of the specified size, returning a pointer to the new node: 

Heap.MakeNode: procedure [ 

z: uncounted zone <- systemZone, n: NWords] returns [long pointer]; 

Heap.MakeMDSNode: procedure [ 

z: MDSZone «- systemMDSZone, n: NWords] returns [pointer]; 

The following two procedures deallocate the specified node. If p is NIL the operation is a no- 
op. 

Heap.FreeNode: procedure [z: uncounted zone «- systemZone, p: long pointer]; 
Heap.FreeMDSNode: procedure [z: MDSZone«- systemMDSZone, p: pointer]; 
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4.7 Logging 

Log: DEFINITIONS 
LogFile: definitions ...; 

These interfaces supply a general purpose facility for recording information in a client- 
supplied log file. These facilities allow logging words, blocks of words, and strings, 
turning the log on and off, limiting the entries placed in the log based on a severity level, 
initializing and resetting the log file, and controlling the action taken when it fills up. 
Additional facilities are provided for subsequently examining the contents of a log file. 
The implementation modules for the logging facility are Loglmpl.bcd and 
LogFilelmpl.bed. 


4.7.1 Writing into the log file 

The procedures in the Log interface are used to write into the log file, and to install the log 
file, start and stop logging, and other control functions. The file used for the log is 
supplied by the client, and its properties (length, type, etc.) are not changed by the logging 
package; only its content is modified. This allows the client to retain control of the log file 
for purposes of examining it, copying it, displaying it to field service personnel, etc. 

4.7.1.1 Installing, opening, and closing the log file 

Install is used to initialize a log file. It is normally called only during system generation 
when a file system is being built. 

Log.lnstall: procedure [file: File.File, firstPageNumber: Fiie.PageNumber*-1]; 

Log.logCap: readonly File.File; 

Log.Error: error [reason: Log.ErrorType]; 

Log.ErrorType: type = machine dependent {illegalLog, tooSmallFile,... }; 

Install will format the file starting at firstPageNumber. Pages preceding firstPageNumber 
will not be used by the logging package. Log.ErrorfillegalLog] is raised if there is already a 
current log file. Log.ErrorftooSmallFile] is raised if the usable size of file is too small. 
Install also automatically performs an Open (see below). The currently installed log file is 
kept in the variable logCap. 

Caution: In the current version of Pilot, the minimum usable size of a log file is 4 pages. 
Also, the logging package will not use more than 256 pages of a log file. 

Log.Open: procedure [file: File.File, firstPageNumber: Fiie.PageNumber<-1]; 

Log.ErrorType: type a {... , invalidFile,... 

Open prepares the logging package to write log entries into file, which becomes the 
currently installed log file . This must be done before any entries may be written into the 
log. Open is typically used after a system restart to re-establish logging on an existing log 
file (one that has already been formatted as a log). This procedure does not reset the 
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contents of the log; new entries will be added to the end. Log.Error[invalidFile] is raised if 
file has not been formatted as a log file, or if logging is currently open on a different file . 
Opening the current log file is a no-op. 

Log.ciose: PROCEDURE H; 

Log.ErrorType: type = {..., logNotOpened,... }; 

Close causes all current log entries to be forced out to the log file and the logging facility to 
stop accessing it. It ceases to be the current log file. Log.Error[IogNotOpened] is raised if 
there is no current log file. 

4.7.1.2 Writing entries in the log file 

Procedures are provided for logging three data types: a single word, a block of words, or a 
string. 

Log.PutWord: procedure [level: log.Level,data: unspecified, forceOut: boolean false]; 
Log.PutBlock: PROCEDURE [ 

level: Log.Level, pointer: long pointer, size: cardinal, forceOut: boolean «- false]; 
Log.PutString: procedure [ 

level: Log.Level, string: long string, forceOut: boolean false]; 

Log.Level: type = Log.State[error..remark]; 

Log.State: type ■ machine dependent {off, error, warning, remark}; 

An entry is only written to the log if its level is less than or equal to the current state (see 
§4.7.1.3). If forceOut is true, the buffer containing the entry is forced out to the file. The 
length of a log entry is restricted to a maximum of 255 words; PutBlock and PutString will 
truncate an entry if necessary. Log.Error[logNotOpened] is raised if there is no current log 
file. Except for their order, the logging package attaches no particular semantics to the 
levels; the names used are meant only to be suggestive of the ordering. 

Log.SetRestart: procedure [message: unspecified]; 

SetRestart allows the client to write a special entry in a log file. This "message” entry is 
the only entry in a log file that may be overwritten. This entry could be used by a backstop 
(see Chapter 9) to communicate to its client when and why the client last crashed. The 
client could obtain this information by reading the restart entry of its backstop’s log file. 
Log.ErrorflogNotOpened] is raised if there is no current log file. 

4.7.1.3 Controlling logging 

The following procedures can be used to control what information is recorded in the log 
file: 

Log.SetState: procedure [state: Log.State]; 
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log.GetState: procedure returns [state: Log.State]; 
tog.Disable: procedure returns [Log.State]; 

Log.Reset: procedure []; 

SetState specifies what levels of log entries are to be written into the log file. 
Subsequently, any call that specifies a level less than or equal to the current state will 
make an entry in the log. The current state is initially set to error. Note that if the state is 
off, all logging calls are ignored, since level is never less than or equal to off. GetState 
returns the current value of the state. Disable sets the current state to off, with the side 
effect of forcing out any internal buffering to backing storage. It also returns the previous 
value of the state. Reset will reset the log file to the beginning, thereby completely 
emptying it; this also flushes buffers. Log.Error[logNotOpened] is raised if there is no 
current log file. 

Log.SetOverflow: procedure [option: Log.Overflow]; 

Log.Overflow: type ■ machine dependent {reset, disable, wrap}; 

SetOverflow allows the client to specify what is to be done when the log file becomes full. 
If reset is specified, the log will start over at the beginning (this will invalidate all 
previous entries). If disable is specified, logging will be turned off; Log entries will 
continue to be accepted, but their contents will be discarded. If wrap is specified, the log 
will behave like a ring buffer, with a new entry overwriting the oldest one. Logging is 
initially set for wrap mode. Log.Error[logNotOpened] is raised if there is no current log 
file. 

4.7* 1.4 Properties of the current log file 

The following procedures can be used to determine the properties of the current log file: 

Log.GetCount: procedure returns [count: cardinal]; 

Log.Getlndex: procedure returns [index: Log.lndex]; 

Log.GetLost: procedure returns [lost: cardinal]; 

Log.GetUpdate: procedure returns [time: System. GreenwichMeanTime]; 

Log.lndex: type a cardinal; 

Log.nulllndex: Index a 0; 

Log.ErrorType: type = {..., logNoEntry,... }; 

GetCount returns the current number of entries, counting from the beginning of the log 
file.Getlndex returns the current index into the log file. GetLost returns the number of 
entries that have been lost due to log overflow (for overflow mode of disable). GetUpdate 
returns the time of the last log entry, or raises Log.Error[logNoEntry] if the log is empty. 
Log.Error[logNotOpened] is raised if there is no current log file. 
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4.7.2 Reading a log file 

The procedures defined in logFile interface are used to examine a log file. They should not 
be applied to the current log file. If it is necessary to read the current log file, the client 
must Log.Close it first. 

If the file supplied to any LogFile operation does not appear to be formatted as a log file, the 
error InvalidFile is raised. If the file is the current log file, the error lllegalEnumerate is 
raised. 

LogFiie.InvalidFile: error; 

LogFiie.lllegalEnumerate: error; 

The following procedures can be used to determine the properties of a log file. They 
parallel those of the same name in the Log interface. 

LogFile. GetCount: procedure [file; File.File, firstPageNumber: File.PageNumber 1] 
returns [count: cardinal]; 

LogFile.GetL.ost: procedure [file: File.File, firstPageNumber: File.PageNumber«- 1] 
returns [count: cardinal]; 

The following procedure is used to enumerate the entries of a log file. 

LogFile. GetNext: PROCEDURE 

[file: File.File, current: Log.lndex, firstPageNumber: File.PageNumber <-1] 
returns [next: Log.lndex]; 

LogFiie.Inconsistent: error; 

GetNext is a stateless enumerator with a starting and ending value of nulllndex. If current 
appears to contain garbage, GetNext will raise Inconsistent. This situation could arise if 
the system crashed before the last page of the log was written to the log file. Therefore, 
this error can be used to detect the last entry before the system crashed. 

LogFile.GetAttributes: procedure 

[file: File.File, current: Log.lndex, firstPageNumber: File.PageNumber«-1] 
returns [time: System.GreenwichMeanTime.type: LogFile.Type, 
level: Log.Level, size: cardinal]; 

LogFile. GetBlock: procedure [file: File.File, current: Log.lndex, 
place: long pointer, firstPageNumber: File.PageNumber «-1]; 

LogFile.GetString: procedure [file: File.File, current: Log.lndex, 
place: long string, firstPageNumber: File.PageNumber <-1]; 

LogFile.Type: type * machine dependent {null (0), block (1), string (2), (63)}; 

LogFiie.DifferentType: error; 
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GetAttributes will return the type, level and size of an entry, as well as the time at which 
it was written. Only two types of entries are returned: If type is set to block, size is the 
number of words in the block. If type is set to string, size is the number of characters in 
the string. A single word log entry is treated as a block of size one. Once the type and size 
of an entry are determined, GetBlock or GetString can be used to copy the entry into 
storage supplied by the client. If GetBlock is called to copy a string entry or GetString is 
called to copy a block entry, the error LogFile.DifferentType is raised. 

LogFile. Reset: procedure [file: File.File, firstPageNumber: File.PageNumber <-1]; 

Reset will reset a log file to be empty. The file could then be reestablished as the current 
log file using Open. 

LogFile. Get Restart: procedure [file: File.File, firstPageNumber: File.PageNumber 1] 

returns [restart: LogFile. Restart]; 

LogFiie.Restart: type = machine dependent record [ 

message(O): unspecified, time(1): System. GreenwichMeanTime]; 

GetRestart allows the client to read a special entry from a log file and to obtain the time 
that entry was last written. This "restart” entry is the only entry in a log file that may be 
read without enumerating the entries. The message returned is the restart supplied to 
Log.SetRestart. If SetRestart was never called for that log file, time will have the value 
System.gmtEpoch and the value of message will be undefined. The "restart" entry might 
be used by a client to examine his backstop's log file to determine when and why he last 
crashed. For the client to interpret message, he must have independent knowledge of the 
values given to message by the system that wrote it. 
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The facilities described in this section provide the lowest level standard access to 
input/output devices through Pilot. Two concepts are defined: software channel and 
device driver. A software channel is a Mesa interface to a device. It specifies all of the 
device-specific data and control information which a client needs to operate the device. A 
device driver is a set of programs which actually implement and export a software channel. 
It includes all of the necessary "interrupt” routines, interfaces with microprograms, 
control of hardware registers, etc., to service the device. It may be part of Pilot or it may be 
supplied by another organization for a special purpose device. 

Initializing a software channel binds the client to a physical resource and device driver. 
Each channel represents a single device. Shared resources, such as common controllers, 
are normally hidden from view so that, for example, each drive unit connected to a 
common controller is treated as a distinct device. The device drivers hold the decision 
making power over the allocation of these shared resources. In the case that this does not 
provide the proper control, it will be necessary to construct a new device driver. 

The concept of software channel is common to all devices and all channels have a common 
style. However, Pilot does not provide a central, common interface to all of them. Instead, 
each channel is represented by its own Mesa definitions module. The common style is 
presented in this section in the form of the specification of a hypothetical device called 
ExampleDevice. The channel interfaces for specific devices exported by Pilot are given 
later in this section. In addition, client development groups may add additional channels 
to Pilot for specialized or private devices. 


5.1 Channel structure and initialization 

To create and initialize a software channel for ExampleDevice , the client calls 

ExampleDevice . Create: PROCEDURE [assign: £xamp/eDev/ce.WhichDevice, 
drive: cardinal] 

returns [Examp/eDev/ce.ChannelHandle]; 

ExampleDevice . \Nh\chDevice: type ■ {any, specified}; 
£xamp/eDev/ce.ChannelHandle: type = private ...; 
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fxamp/eOewce.DeviceNotAvailable:...; 

The assign parameter indicates how to choose among multiple instances of a device." If any 
is specified, the device driver allocates any instance of that device. If specified is passed, 
then the device driver selects the drive indicated by drive. If the channel cannot be 
initialized for any reason, the routine signals fxamp/eDev/ce.DeviceNotAvailable. 

Device drivers which support multiple instances of a device also define the operation 

Examp/eOewce.GetDrive: procedure [channel: Examp/eDev/ce.ChannelHandle] 
returns [drive: cardinal]; 

This operation is used to identify the specific device associated with the ChannelHandle. 
Deleting a channel and releasing the associated device are accomplished by 

ExampleDevice . Delete: PROCEDURE [channel: Examp/eDewce. ChannelHandle]; 

This operation calls ExampleDevice . Abort before returning. If the client wishes to complete 
all pending transfers he should first call ExampleDevice . Suspend . 

The following operations allow a client to control the data transfer activity on a specific 
device. 

ExampleDevice.Suspend : procedure [channel: fxamp/eOewce.ChannelHandle]; 

This operation waits for all pending transfers (i.e., as a result of previously executed calls 
on ExampleDevice.G et and Examp/eDewce. Put) to complete before returning. Subsequent calls 
on Get, Put, or any control operations are ignored. However, calls on TransferWait for 
previously outstanding transfers will return normally. 

ExampieDevice . Restart: procedure [channel: Examp/eDewce.ChannelHandle]; 

This operation restarts a suspended channel. A channel may become suspended (with no 
pending operations) as a result of the Suspend operation or (with some operations 
pending) as the result of the occurrence of a sufficiently serious error. 

ExampleDevice . Abo rt: procedure [channel: ExampleDevice . ChannelHandle]; 

This operation aborts all activity on the indicated channel. Any outstanding data transfer 
operations will be immediately terminated with a TransferStatus = [true, aborted] (see 
§5.1.1.3 for TransferStatus). 

5.1.1 Data transfer 

The operations described below transmit information to and from a device. This data 
transfer is asynchronous so that many input and output operations can be simultaneously 
pending. 

Each device may impose its own constraints on the alignment of data in memory. This is 
specified by three constants declared (statically) in the interface to the software channel. 
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fxamp/eDev/ce.alignment: cardinal » ...; 
fxamp/eDevice.granularity: cardinal = 
fxamp/eDewce.truncation: cardinal = ... ; 

These three values must be specified and clients of devices must adhere to them. These 
requirements are normally imposed by certain high-performance devices to maintain 
physical memory bandwidth, satisfy physical constraints in the implementation of the 
controllers, etc. In particular, the device may constrain: 

each I/O buffer to be aligned on a virtual memory address which is a multiple of 

alignment; 

each I/O buffer in virtual memory to have a length which is an integral multiple of 

granularity; and 

each physical record on the device to have a length which is a multiple of truncation. 

Each of these constants must be a power of two in the range [0. .256]. A value of zero is 
interpreted to represent byte alignment, granularity, and truncation; a value of one 
represents word alignment, granularity, and truncation; a value of four represents 
quadword alignment, granularity, and truncation; a value of sixteen represents 16-word 
alignment, granularity, and truncation; and a value of 256 represents page alignment, 
granularity, and truncation. 

Normally, granularity is greater than or equal to truncation. On output, the buffer must 
be a multiple of granularity, but the physical record may be truncated to a multiple of 
truncation. On input, the buffer must also be a multiple of granularity. If a shorter (i.e., 
truncated) record is read, the remainder of the buffer may be filled with garbage. 

5.1.1.1 Data transfer types 

The following data structures are the most general form for describing the source or 
destination of the data being transferred. Specific software channels may define simpler 
versions of these which, for example, omit the header or trailer, startlndex, etc. 

£xamp/eDev/ce.PhysicalRecordHandle: type = long pointer to £xamp/e0ev/ce.PhysicalRecord; 

£xamp/eDew'ce.PhysicalRecord: type = record [header: ExampieDevice.B lockDesc, 
body: ExampleDevice. BiockDesc, trailer: £xamp/eDewce.BlockDesc]; 

Exam pie Device . BI Ock DeSC: TYPE = RECORD [blOCkPointer: LONG POINTER TO UNSPECIFIED, 

startlndex,stopIndexPlusOne: cardinal]; 

The PhysicalRecord specifies control information for the transfer operation in the header 
and trailer. The body specifies the buffer to or from which data is transferred. Quantities 
such as disk addresses and communication packet routing information are placed in the 
header and trailer blocks in a device dependent way. 
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If necessary, the alignment, granularity, and truncation may be specified separately for 
the header, body, and trailer. 

£xamp/eDevfce.CompletionHandle: type = private ...; 

The CompletionHandle identifies the I/O transaction initiated by a Get or a Put operation. 
It is passed as parameter to the TransferWait operation, which does not return until that 
particular I/O operation is completed. Get and Put are asynchronous and return to the 
caller as soon as the request has been queued and made pending. TransferWait completes 
the operation and returns the number of bytes transferred and the resulting 
TransferStatus. 

5.1.1.2 Data transfer procedures 

ExampleDevice . Get: PROCEDURE [channel: fxamp/eDewce.ChannelHandle, 
rec: fxamp/eOev/ce.PhysicalRecordHandle] 
returns [ExampleDevice, CompletionHandle]; 

This operation queues the PhysicalRecord for input transfer and returns to the client with 
the input transfer pending. The CompletionHandle must be submitted to the 
TransferWait operation in order to complete the transfer and before any of the input 
information can be used. 

ExampleDevice, Put: procedure [channel: ExampleDevice. ChannelHandle, 
rec: ExampleDevice .Physical Record Handle] 
returns [Examp/eDev/ce.CompletionHandle]; 

This operation queues the PhysicalRecord for output transfer and returns to the client 
with the output transfer pending. The CompletionHandle must be submitted to the 
TransferWait operation in order to complete the transfer and before the output record can 
be reused. 

For both Get and Put, the I/O buffers described by the PhysicalRecord must not be released, 
altered, or reused until after the TransferWait operation for this transfer completes. In 
particular, any control information contained, for example, in the header or trailer buffers 
will be read or processed in place by the device rather than stored internally. 

Examp/eOewce.TransferWait: procedure [channel: Examp/eDev/ce.ChannelHandle, 
event: ExampleDevice. CompletionHandle] 

returns [byteCount: cardinal, status: Examp/eDev/ce.TransferStatus]; 

This operation completes the processing of the I/O and returns the number of bytes 
transferred and the status to the client. The CompletionHandle specifies the particular 
pending transfer to await. If the channel has been aborted, status = [true, aborted]. 

5.1.1.3 Data transfer status 

Transferring data can provoke a number of errors. When a serious error occurs, the 
channel is suspended. In any case Pilot returns the TransferStatus as the result of the 
TransferWait procedure. The client can then examine this status and take corrective 
action. If this status indicates that the channel has been suspended, it must be restarted 
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after corrective action is taken and before any further data transfers are possible. A 
Restart allows I/O transactions to continue over the channel. 

fxamp/eOev/ce.TransferStatus: type = record [error: boolean, 
type: £xamp/eDev/ce.TransferErrors]; 

£xamp/eDewce.TransferErrors: type a {aborted,... }; 

If no errors were encountered then error is false. If errors were encountered then error is 
true and the particular error is identified in type. 


5.1.2 Device specific commands 

Most devices need a number of device specific auxiliary operations which are not specified 
by the common channel style. Rewind for a magnetic tape is an example. 

Some of these operations are for direct and simple communication with the device driver 
and involve no physical I/O, e.g., 

Examp/eDev/ce.SetNumberOfRetries: procedure [channel: ExampieDevice. ChannelHandle, 
numberOfRetries: cardinal]; 

Others might invoke an I/O operation which is not a data transfer, e.g., 

ExampieDevice. Rewind: procedure [channel: ExampieDevice- ChannelHandle]; 

Completion of this kind of operation is detected via StatusWait described below. 

Yet others might initiate I/O operations which are similar to data transfers and may 
choose to use the CompletionHandle and TransferWait mechanisms to detect completion, 
e.g., 

fxamp/eDev/ce.VerifyData: procedure [channel: ExampieDevice. C hannelHandle, 
rec: £xamp/eDev/ce.PhysicalRecordHandle] 
returns [fxamp/eDevice.CompletionHandle]; 

5.1.3 Device status 

In addition to the status information returned for each data transfer operation, Pilot 
maintains global information about the device itself in the DeviceStatus record. This 
contains state information about the static and long term state of the device. It is accessed 
via the GetStatus and StatusWait procedures. 

ExampieDevice- DeviceStatus: TYPE = RECORD [...]; 

ExampieDevice- GetStatus: procedure [channel: fxamp/eOewce.ChannelHandle] 
returns [ExampieDevice- DeviceStatus]; 

ExampieDevice. $tatus\Nsit: procedure [channel: Examp/eOev/ce.ChannelHandle, 
stat: ExampieDevice- DeviceStatus] 
returns [ExampieDevice- DeviceStatus]; 
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StatusWait waits until the current DeviceStatus differs from the supplied parameter stat. 
The client must examine the device status to determine what action to take. 

5.2 Keyset, keyboards, and mouse 

Keys: definitions ...; 

Keystations: definitions 
LevelIVKeys: definitions 
LevelVKeys: definitions ...; 

JLevellVKeys: definitions 

The state of the keys on the keyboard is described by an array of bits. These are packed 
into an array of words maintained by Pilot but readable by the client. The following 
exported variable provides access to this array. 

UserTerminal. key board: readonly long pointer to readonly array of word; 

The mouse buttons and the keyset are considered keys and therefore occupy positions in 
this array. 

The interpretation of the bits of this array is not specified by Pilot, but is instead specified 
by one or more separate definitions modules associated with each particular keyboard. 
This permits Pilot to support more than one kind of keyboard layout. In the current 
version of Pilot, there are three such definitions modules. LevelIVKeys defines the bits for the 
U.S. Dandelion keyboard, JLevellVKeys, the Japanese Dandelion keyboard, and LevelVKeys, 
the Dove keyboard. 

The Keys and Keystations modules are obsolete and are included only for backward 
compatibility. 

Figures 5.2a, 5.2b, and 5.2c at the end of this section show the assignments of keys on the 
keyboards to bits in the UserTerminal. keyboard array. 

The table below lists the names given to each bit in the UserTerminal. keyboard array by the 
LevelVKeys interface. For historical reasons, the key names are not always the same as the 
names printed on the keyboards. The columns in the table have the following meaning. 

Bit: the nth element in the UserTerminal. keyboard bit array. 

Name: the key name used to refer to this bit. 


Bit 

Name 

Bit 

Name w 

0 

__ 

56 

Z 

1 

Bullet 

57 

LeftShift 

2 

SuperSub 

58 

Period 

3 

Case 

59 

SemiColon 
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4 

Strikeout 

60 

NewPara 

5 

KeypadTwo 

61 

OpenQuote 

6 

KeypadThree 

62 

Delete 

7 

SingleQuote 

63 

Next 

8 

KeypadAdd 

64 

R 

9 

KeypadSubtract 

65 

T 

10 

KeypadMultiply 

66 

G 

11 

KeypadDivide 

67 

Y 

12 

KeypadClear 

68 

H 

13 

Point 

69 

Eight 

14 

Adjust 

70 

N 

15 

Menu 

71 

M 

16 

Five 

72 

Lock 

17 

Four 

73 

Space 

18 

Six 

74 

LeftBracket 

19 

E 

75 

Equal 

20 

Seven 

76 

RightShift 

21 

D 

77 

Stop 

22 

U 

78 

Move 

23 

V 

79 

Undo 

24 

Zero 

80 

Margins 

25 

K 

81 

KeypadSeven 

26 

Dash 

82 

KeypadEight 

27 

P 

83 

KeypadNine 

28 

Slash 

84 

KeypadFour 

29 

Font 

85 

KeypadFive 

30 

Same 

86 

English 

31 

BS 

87 

KeypadSix 

32 

Three 

88 

Katakana 

33 

Two 

89 

Copy 

34 

W 

90 

Find 

35 

Q 

91 

Again 

36 

S 

92 

Help 

37 

A 

93 

Expand 

38 

Nine 

94 

KeypadOne 

39 

I 

95 

DiagnosticBitTwo 

40 

X 

96 

DiagnosticBitOne 

41 

O 

97 

Center 

42 

L 

98 

KeypadZero 

43 

Comma 

99 

Bold 

44 

Quote 

100 

Italic 

45 

RightBracket 

101 

Underline 

46 

Open 

102 

Superscript 

47 

Special 

103 

Subscript 

48 

One 

104 

Smaller 

49 

Tab 

105 

KeypadPeriod 

50 

ParaTab 

106 

KeypadComma 

51 

F 

107 

LeftShiftAlt 

52 

Props 

108 

DoubleQuote 

53 

C 

109 

Defaults 

54 

J 

110 

Hiragana 

55 

B 

111 

RightShiftAlt 
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Dandelion US Key Numbering 


Fig. 5.2.a - Level IV Keyboard 
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Dove US Key Assignments 



Fig. 5.2.b - Level V Keyboard 
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Fig. 5.2.c- Level V Keyboard 
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5.3 The user terminal 

UserTerminal: definitions ...; 

UserTerminalExtras: definitions 

UserTerminal describes the state of the user input/output devices - the display image (as 
represented by a one-bit-per-pixel bitmap), the display cursor, the keyboard, the mouse, 
and the keyset ~ and allows the client to manipulate them. This interface assumes the 
configuration of the user terminal is as is given above. It does allow the client to deal with 
variations such as the number of keys or the size and resolution of the display. This 
interface deals with many of the lowest level attributes of the terminal Within a typical 
client system, only a small user interface component will call UserTerminal directly. 
Definitions and operations of general interest are presented first, followed by more 
specialized ones. 

UserTerminalExtras provides interim support for smooth scrolling. It will become part of 
UserTerminal in a future version of Pilot. 

5.3.1 The display image 

UserTerminaLscreenWidth: readonly cardinal [0..32767]; 

UserTerminal.screenHeight: readonly cardinal [0..32767]; 

UserTerminal. pixelsPerlnch: READONLY cardinal; 

The attributes of the image are defined by the above exported variables. screenWidth and 
screenHeight specify the number of usable, visible picture elements in a row or column of 
the screen. 

The bitmap image is addressed by x-y coordinates. The coordinate origin (0, 0) is the 
uppermost, leftmost pixel of the display; x increases to the right, and y increases 
downward. 

UserTerminal.Coordinate: TYPE = MACHINE DEPENDENT RECORD [x, y: INTEGER]; 

The state of the display is defined as 

UserTerminal. State: type * {on, off, disconnected}; 

where 

on indicates the display is physically on and visible to the user (and a bitmap is 
allocated); 

off indicates the display is physically off and not visible to the user (but a bitmap is 
allocated); 

disconnected indicates the same as off but with no bitmap allocated. 

Clients may determine the current state of the bitmap display by calling 
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UserTerminai.GetState: PROCEDURE RETURNS [state: UserTerminal.State]; 

The bitmap display is capable of displaying black-on-white or white-on-black. Clients 
may determine or alter the current state of the background by using the following 
procedures. In the image, a pixel whose value is one is considered the figure; a pixel of 
zero, background. 

UserTerminaLGetBackground: PROCEDURE 

returns [background: UserTerminal.Background]; 

UserTerminal.SetBackground: procedure [new: UserTerminal.Background] 
returns [old: UserTerminal.Background]; 

UserTerminal.Background: type = {white, black}; 

Clients may momentarily blink (video reverse) the display by calling 

UserTerminai. BlinkDisplay: PROCEDURE; 

Some displays have the capability to display a border around the outside of the active 
display region. Clients can determine if the display has this capability by interrogating 
the following exported variable. 

hasBorder: readonly boolean; 

If the display has a border, then clients may set the pattern to be displayed in the border 
by calling 

UserTerminai. SetBorder: procedure [oddPairs, evenPairs: [0..377B]]; 

The bit pattern for an individual scan line is defined by displaying a single byte repeatedly 
along the entire scan line The same pattern is shown on alternating pairs of lines. Thus, 
evenPairs is the byte used on lines -4, -3, 0, 1,4. 5. etc.; oddPairs is the byte used on lines - 
2, -1, 2, 3, 6, 7, etc. Calling SetBorder when hasBorder is false will lead to unpredictable 
results. 

The following function is provided for clients who need to synchronize bitmap alteration 
with display refresh. Waiting for scan line zero is also a commonway for a user input 
handler to wait between polls of the keyboard and mouse buttons. 

userTerminal.WaitForScanLine: procedure [scanLine: integer]; 

The following procedure will return a BitBlt table with the bitmap fields filled in for the 
current bitmap. 

UserTerminai. GetBitBltTable: PROCEDURE returns [bbt: BitBit.BBTable]; 

The bitmap parameters are returned in bbt in such a fashion that a BitBlt using it will 
copy the bitmap from itself to itself. For a complete description of a BBTable see the 
description of BitBlt in the Mesa Processor Principles of Operation, The bits-per-line in 
the returned bbt may be different than screenWidth if the display implementation has 
non-visible padding bits appended to each line. 


5-12 




Pilot Programmer’s Manual 


5 


WaitForScanLine and GetBitBltTable will raise the following error if the display is 
disconnected (deallocated). 

UserTerminal.BitmapisDisconnected : error; 

Clients may alter the state of the bitmap and display by calling 

UserTerminal. SetState: PROCEDURE [new*. UserTerminal. State] 

RETURNS [old: UserTerminal. State]; 

Setting the state to disconnected invalidates any BBTables previously returned by 
GetBitBltTable, but setting the state to off does not. The bitmap is zeroed (i.e., set to all 
background) when the state is changed from disconnected to on. Disconnecting destroys 
any information that may have been contained in the bitmap. 

UserTerminal.CursorArray: type = array [0..16) of word; 

The display cursor is defined by a 16x16 bit array, whose bits are OR’ed with the bitmap. 
The top row is contained in CursorArray[0]; the bottom row in CursorArray[15]. The most 
significant bits of each entry in the array correspond to the left portion of the cursor 
image: the least significant bits correspond to the right portion. 

Clients can determine the current bit pattern for the cursor by calling 

userTerminal.GetCursorPattern : procedure 

returns [ cursorPattern: UserTerminal.CursorArray]; 

The cursor pattern is set by calling 

UserTerminal.SetCursorPattern: procedure [cursorPattern: UserTerminal.CursorArray]; 

The coordinates of the cursor can be found by the following exported variable. 

UserTerminal.Cursor: READONLY LONG POINTER TO READONLY UserTermmal.Coordinate; 

The position of the cursor on the display may be altered by calling the procedure 
UserTerminal.SetCursorPosition: procedure [newCursorPosition: UserTermmal.Coordinate]; 

5.3.2 Smooth scrolling 

The smooth scrolling interface allows a client to create a window within the display area 
that can be scrolled up or down. Clients may create a scroll window by calling 

UserTerminalExtras.CreateScrollWindow: procedure [locn: UserTermmal.Coordinate, 
width: cardinal, height: cardinal]; 

UserTerminalExtras.SCrollXQuantum: READONLY CARDINAL,* 

UserTerminalExtras.scroll YQuantum: READONLY CARDINAL; 

UserTerminalExtras.Error: ERROR [type: UserTerminalExtras.ErrorType]; 
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UserTerminaiExtras.ErrorType: type = {multipleWindows,..yQuantumError, 
xQuantumError}; 

The horizontal bit-position of the scroll window within the bitmap (loc.x) and the width of 
the scroll window (width) must be multiples of scrollXQuantum. The vertical bit position 
of the scroll window (loc.y) and the height of the scroll window (height) must be multiples 
of scroilYQuantum. Thus, a value of 16 for scrollXQuantum indicates that left and right 
edges are word aligned within the bitmap. 

If the constraints on loc, height, and width are not observed, Error[xQuantumError] or 
Error[yQuantumError] will be raised. Error[multipleWindows] will be raised if a scroll 
window already exits. 

UserTerminalExtras.SCrollinglnhibitsCursor: READONLY boolean; 

On some processors, the presence of a smooth scrolling window inhibits display of the 
cursor, in which case scrollinglnhibitsCursor is true. 

Clients cause the display to be scrolled up or down by calling 

UserTerminalExtras. Scroll: PROCEDURE [line: LONG POINTER TO UNSPECIFIED, lineCount: CARDINAL, 
increment: integer]; 

UserTerminaiExtras.ErrorType: type = {..noScrollWindow, lineCountError,...}; 

This procedure adds scan lines to the top or bottom of the scroll window, causing the 
window to scroll up or down, line points to the first bit within the first scan line to be 
moved into the scroll window. lineCount indicates how many scan lines are to be moved 
into the scroll window. lineCount must be a multiple of scroilYQuantum. The number of 
lines moved into the scroll window each time controls the speed of the scrolling. As each 
scan line is moved into the scroll window, increment is added to line to produce the bit 
address of the next scan line The direction of the scroll is specified by the sign of 
increment. If increment is positive, lines are added to the bottom of the window, causing it 
to scroll up If increment is negative, lines are added to the top of the window, causing it to 
scroll down. 

During scrolling, the scan lines in the scroll window portion of the bitmap may not be in 
the same order in memory as they appear on the display. 

If no scroll window exists, the error Error[noScrollWindow] will be raised. If lineCount is 
not a multiple of scroilYQuantum, Error[lineCountError] will be raised. 

The scroll window may be deleted by calling 

UserTerminalExtras. DeleteScrol I Window: PROCEDURE,* 

If scrollinglnhibitsCursor is true, there may be a delay before the cursor appears again 
while the scan lines in the scroll window are being sorted into their proper order. 

The error Error[noScrollWindow] will be raised if no scroll window exists. 
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5.3.3 The keyboard and keyset 

The keyboard and keyset defined in this interface are uninterpreted. That is, up/down key 
transitions are noted by the state of the bits in the following unencoded array: 

UserTerminal. key board : READONLY LONG POINTER TO READONLY ARRAY OF WORD; 

UserTermina!Extras2.keyboardType: readonly KeyBoardType; 

UserTerminalExtras2.KeyBoardType: TYPE a MACHINE DEPENDANT { 

learSiegler(O), Ievel4(1), jLevel5(2), Ievel5(3), other(LAST[CARDiNAL])}; 

keyboardType gives the type of the keyboard attached to the system element. learSiegler 
implies that a Lear Siegler CRT is attached Ievel4 implies that a Level 4 keyboard is 
attached; this is the keyboard usually attached to Dandelion processors. jLevel5 is a Level 
5 keyboard for JStar. Ievel5 is the American version of the Level 5 keyboard. 

The Extras interface is interim for this release and will be merged with its parent interface 
in future releases. 

5.3.4 The mouse 

The coordinates of the mouse can be found by the following exported variable 

UserTerminal. mouse : READONLY LONG POINTER TO READONLY UserTerminal.Coordi nate; 

Clients can alter the coordinates of the current mouse position by calling 

UserTerminal. SetMousePOSition: PROCEDURE [newMousePosition: UserTerminal. Coordinate]; 

5.3.5 The sound generator 

This procedure allows generating simple tones on processors equipped with suitable 
hardware: 

UserTerminal.Beep: procedure [frequency: CARDINAL <- 1000, 
duration: cardinal 4- 500]; 

Beep sounds a tone of the given frequency (specified in hertz) for the specified duration, 
specified in milliseconds. The procedure is synchronous, it does not return until the beep 
has been generated. A Beep may be prematurely terminated using Process.Abort. 

On the Dandelion, frequencies lower than 29 Hz are rounded up to 29 Hz. The practical 
upper limit is human audibility. The granularity of the duration is one process timeout 
tick (about 50 ms.). The specified frequency is actually rounded up to the next frequency 
which exactly divides 1.8432 MHz. 
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5.4 Floppy disk channel 

FloppyChannel: definitions ... 

The floppy disk is supported in Pilot in two modes: as a Pilot floppy file system, and as a 
direct software channel. The two forms of access are mutually exclusive. This section 
addresses the second form, channel access. 

i 

The FloppyChannel interface to the floppy disk provides the client direct sector-level access to 
the floppy disk. This interface allows the client to check and set drive- and diskette- 
specific characteristics, to check drive status, and to read and write sectors or groups of 
sectors. Logical formatting of the disk is the responsibility of the client. 

Each drive is accessed by a Handle 

FloppyChannel.Handle: TYPE [2]; 

FloppyChannel.nullHandle: readonly Handle; 

FioppyChannei.Error: error [type: FloppyChannel.ErrorType]; 

FloppyChannel. ErrorType: type = {. .invalidHandle,.. 

For all of the floppy channel operations that take a Handle as an argument, the error 
FloppyChannel.ErrorfinvalidHandle] is raised if the Handle is not valid. A Handle is.invalid if 
the drive that it refers to has changed state (i.e., gone from not-ready to ready or from 
ready to not-ready) since the Handle was acquired. 

The following frequently used types are available for the convenience of FloppyChannel 
clients. 

FloppyChannel. Density: type « {single, double}; 

FloppyChannel.Format: type = {IBM, Troy}; 

FloppyChannel.HeadCount: type a [0..256); 

FloppyChannel.SectorCount: TYPE a [0..256); 

5.4.1 Drive characteristics 

The Attributes record contains the characteristics of the specific drive connected to the 
floppy disk controller and of the diskette currently installed. 

FloppyChannel. Attributes: TYPE = RECORD [ 

deviceType: DeviceType, numberOfCylinders: CARDiNAL,numberOfHeads: HeadCount, 
maxSectorsPerTrack: SectorCount,formatLength: cardinal, ready: boolean, 
diskChange: boolean, twoSided: boolean] 

deviceType indicates the type of drive connected to the controller; numberOfCylinders is 
the number of cylinders available for recording on that drive; numberOfHeads is the 
number of read/write heads available on that drive; maxSectorsPerTrack is the maximum 
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number of sectors per track of the diskette (based on context setting); formatLength is the 
size of the buffer, in words, needed in order to format the diskette; ready indicates whether 
the drive contains a diskette or not; diskChange indicates whether the drive has gone from 
ready to not-ready (door open), or from not-ready to ready, one or more times since the last 
operation was performed; and twoSided indicates whether the diskette currently installed 
has data on both sides. 

5.4.2 Diskette characteristics 

FioppyChannei.Context: type = record [protect: boolean, format: Format, 
density: Density, sectorLength: cardinal[0..1024]]; 

The values of format, density, and sectorLength are determined when the diskette is 
formatted. Software write-protect can be selected by the client software by setting the 
protect flag. The actual write fault status is a logical OR of this variable and the physical 
signal being returned from the drive. The Troy format is the Xerox 850 format. Note that 
track 00 on IBM format diskettes, and all tracks of Troy format diskettes will be single 
density. sectorLength is the length in words of the sectors on the current track. The value 
must come from a valid set defined as {64, 128, 256, 512} for IBM format and {1022} for 
Troy format. 

The context must be set, via SetContext, before any drive access procedures are called. 
GetContext returns the current context settings 

FloppyChannel.GetContext: PROCEDURE [handle: FfoppyChannel.Handle] 

RETURNS [context: FioppyChannei.Context]; 

FloppyChannel.SetContext: PROCEDURE [handle: FloppyChannel.Handle, 
context: FioppyChannei.Context] 

RETURNS [ok: boolean]; 

The client must provide the context setting which matches the actual format of the 
diskette. SetContext does not cause the diskette to be reformatted. 

5.4.3 Status 

The Status of the drive and operation is returned by any drive access operation. 

FloppyChannel. Status*. TYPE = MACHINE DEPENDENT{ 

goodCompletion, diskChange, notReady, cylinderError, 
deletedData, recordNotFound, headerError, dataError, 
dataLost, writeFault, otherError[LAST[CARDiNAL]}; 

The meanings assigned to the fields in the status record are: 

goodCompletion The operation has completed normally. 

diskChange The disk drive has apparently gone from a ready to a not 

ready state (door open), or vice versa, one or more times 
since the last operation was performed. 
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notReady 

The drive is not ready (does not contain a diskette). 

cylinderError 

The cylinder specified by the disk address can not be 
located 

deletedData 

The record ID for the sector contained a deleted data 
address mark in the header. 

recordNotFound 

The record defined by the disk address could not be found. 

headerError 

A bad checksum was encountered on the header field. 

dataError 

A bad checksum was encountered on the data field. 

data Lost 

A sector has been found on the diskette that is larger than 
that of the current context. 

writeFault 

Logical OR of the context setting of protect, and the 
physical signal being returned from the drive. 

otherError 

An unexpected software or hardware problem has 
occurred. 


5.4.4 Transfer operations 

Transfer procedures move the specified number of sectors to or from the diskette. Seek, 
error recovery, and wait for completion or error are included. 

FloppyChannel.DiskAddreSS: TYPE = MACHINE DEPENDENT RECORD [cylinder: CARDINAL, 
head: HeadCount, sector: SectorCount]; 

The cylinder and head fields must reference a valid cylinder and head as defined by the 
Attributes record. The value of sector must be in the range defined by 

Context.sectorLength. 

FloppyChannel.ReadSectOrs: PROCEDURE [handle: FloppyChannel.Handle, 

address: FloppyChannel.DiskAddreSS, buffer: long pointer, count: cardinal «- 1 , 
incrementDataPtr: boolean «-true] 

returns [status: FioppyChannei.Status, countDone: cardinal]; 

FloppyChannel.WriteSectors: PROCEDURE [handle: FloppyChannel.Handle, 

address: FloppyChannel.DiskAddreSS, buffer: long pointer, count: cardinal «- 1 , 
incrementDataPtr: boolean «-true] 

returns [status: FioppyChannei.Status, countDone: cardinal]; 

FioppyChannel.WriteDeletedSectors: procedure [handle: FloppyChannel.Handle, 

address: DiskAddress, buffer: long pointer, count: cardinal «— 1 , incrementDataPtr: 
boolean «-true] 

returns [status: FioppyChannei.Status, countDone: cardinal]; 
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FioppyChannei.ReadID: PROCEDURE [handle: FioppyChannei.Handle, 
address: FioppyChannei.DiskAddress, buffer: long pointer] 

RETURNS [status: EloppyChannel. Status]; 

The count parameter in the above calls indicates the number of sectors to be transferred. 
The incrementDataPtr parameter determines if buffer is advanced on multiple sector 
transfers. If incrementDataPtr is true, succeeding sectors are read and written advancing 
through the buffer. If it is false, all transfers occur using the same sector buffer. The 
latter might be used to write the same data into a number of sectors, or to read in order to 
verify sectors. 

WriteSectors and WriteDeletedSectors do a read-after-write to verify that the data is 
readable. 

ReadID reads 3 words of device dependent data into the buffer. This operation is provided 
primarily for diagnostics. 

Multiple sector transfers which begin on track 0 of an IBM-formatted diskette and 
continue on to subsequent tracks will produce an error if the format of the remainder of 
the diskette is different from the track 0 format (single density, 64-word sectors). 

5.4.5 Non-transfer operations 

The non-transfer operations access the drive in the same manner as the transfer 
operations, but no data is moved. Nop returns a status. FormatTracks formats the specified 
tracks. 

FloppyChannel.Nop: procedure [handle: FioppyChannei. Handle] 

RETURNS [status: FioppyChannei. Status]; 

FloppyChannei.FormatTracks: procedure [handle: FioppyChannei.Handle, 
start: FioppyChannei.DiskAddress, trackCount: cardinal] 
returns [status: FioppyChannei.Status, countDone: cardinal]; 

Analogous to the PhysicalVolume interface, FioppyChannei provides the following operations. 

FioppyChannei. Drive: TYPE = CARDINAL; 

FloppyChannel.GetNextDrive: PROCEDURE [lastDrive: FloppyChannel.Drive] 
returns [nextDrive: FloppyChannel.Drive]; 

FloppyChannel.nuilDrive: FloppyChannel.Drive = . . .; 

FioppyChannei. GetHandle : procedure [drive: FloppyChannel.Drive] 
returns [handle: FioppyChannei.Handle]; 

FioppyChannel.InterpretHandle: procedure [handle: FioppyChannei.Handle] 

RETURNS [drive: FloppyChannel.Drive]; 

FloppyChannel.ErrorType: type = {invalidDrive,.. 
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GetNextDrive is a stateless enumerator of the floppy drives attached to the system 
element. It begins with nullDrive as an argument and terminates with nullDrive as its 
result. A Handle is obtained by calling GetHandle. The Drive corresponding to a Handle 
may be obtained by calling InterpretHandle. invalidDrive is raised by GetHandle and 
GetNextDrive if they are passed an invalid Drive. 

5.5 Floppy file system 

Floppy: DEFINITIONS 

Floppy is the interface for the Floppy file system. Floppy provides a read/write file system 
only. Direct mapping of floppy files to Pilot spaces is not supported by Floppy. The 
implementation module is named Floppy Impl. bed. 

5.5.1 Accessing files on the diskette 

The floppy diskette contains a collection of files. As with Pilot volumes on rigid disks, each 
file is a sequence of 256-word blocks called pages. A page corresponds to a sector on the 
diskette. Diskette space management and the directory of extant files is kept in a 
structure called the file list. Under most circumstances, users will not need to manipulate 
the contents of file lists. 

Floppy. FilelD: type [2]; 

Floppy. PageNumber: type ■ [0.. — max pages per diskette —); 

Floppy. PageCount: type = [0.. — max pages per diskette — ]; 

Files are identified by values of the type FilelD These are uninterpreted 32-bit quantities 
assigned uniquely within a given floppy diskette. FilelDs are not unique from one diskette 
to another. In particular, if a diskette is copied, the new diskette will have the same files 
with the same FilelDs as the old. Although it is the intention of the implementation not to 
reuse FilelDs, they are not guaranteed to be unique in time for a given diskette (i.e., it is 
possible for a FilelD to be assigned to a file and later for that file to be deleted and the FilelD 
to be subsequently reused). 

Note: PageNumber and PageCount are actually defined as long cardinal since the 
current version of Mesa does not permit subranges of LONG cardinal. 

In order to access a floppy diskette, the client must specify a handle of type: 

Fioppy.VolumeHandle: type [2J; 

Floppy. nullVolumeHandle: readonly Fioppy.VolumeHandle; 

Floppy. Error: error [type: Floppy. ErrorType]; 

Floppy. ErrorType: type = { . .invalidVolumeHandie,.. 

A VolumeHandle is assigned when the floppy is opened (using Floppy. Open) A 
VolumeHandle becomes invalid if the floppy drive door is opened, or if the drive is closed 
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and reopened, even if the diskette remains the same. Values of type VolumeHandle are 
not reused within a given instantiation of Pilot (i.e., from one boot to the next). 

All of the operations that take a VolumeHandle as an argument will raise 

Floppy.Error[invalidVolumeHandle] if presented with an invalid VolumeHandle. 

A complete specification of a floppy file is given by 

Fioppy.FileHandle: type ■ record [volume: Floppy.VolumeHandle, file: Floppy.FilelD]; 

All operations in this interface are synchronous. That is, they do not return to the client 
until they are complete. If a diskette is withdrawn between operations, the Pilot floppy 
file system will not require scavenging (however, the client files may not be well-formed). 

In order to access the floppy at all, the volume must be opened. 

Fioppy.Open: procedure [drive: cardinal 4-0] returns [vol: Floppy.VolumeHandle]; 

Fioppy.ErrorType: type = {..., notReady, noSuchDrive, invalidFormat, needsScavenging, 
invalidVolumeHandle.. 

The operation Open opens the floppy volume and prepares it for all subsequent operations. 
The drive argument indicates which floppy drive is intended if there is more than one 
present. 

If there is no diskette in the drive or for some other reason the drive is not ready, then the 
error Floppy.Error[notReady] is raised. If drive specifies an unknown device then 
Floppy.Error[noSuchDrive] is raised. If the diskette is not formatted according to the 
standard supported by Pilot floppies, Floppy.Error[invalidFormat] is raised. Finally, if Pilot 
cannot properly read in the file list or if the volume otherwise appears to not be well 
formed. Floppy.ErrorfneedsScavenging] is raised. In any of these cases, the volume is not 
opened. 

FioppyExtrasExtras.GetDrive: procedure [ VolumeHandle: Floppy.VolumeHandle] 
returns [ drive: cardinal]; 

GetDrive returns the floppy drive associated with the given VolumeHandle. 
Floppy. ErrorfinvalidHandle] may be raised 

Fioppy.Close: procedure [vol: Floppy.VolumeHandle]; 

Fioppy.ErrorType: type = { ..., volumeNotOpen,.. 

If the user withdraws the diskette from the drive, or for some other reason it becomes not- 
ready, the next operation on the floppy will implicitly close the volume and will raise 
Floppy.ErrorfvolumeNotOpen]. Alternatively, an open volume may be closed by calling 
Close. Close, whether called implicitly or explicitly, merely causes Pilot to forget about the 
floppy. It does not flush buffers, write out data from its caches or tables, etc. Thus, closing 
a closed volume is a no-op. 

The principal operations on floppy files are to read from or write to them sequences of 
pages. 
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fioppy.Read, Write: procedure [file: Fioppy.FileHandle, first: Fioppy.PageNumber, 
count: Fioppy.PageCount, vm: long pointer]; 

Floppy.ErrorType: type s {..., fileNotFound, endOfFile, writelnhibited, 
hardwareError.. 

Fioppy.DataError: error [file: Fioppy.FileHandle, page: Floppy.PageNumber, 
vm: long pointer]; 

These two operations are analogous to Space.Copyln and Space.CopyOut; i.e., they cause a 
sequence of pages to be copied to or from the area in virtual memory designated by vm 
(this pointer must point to the beginning of a page). The sequence is selected from the 
floppy file designated by file, starts with the page numbered first within that file and 
continues for count pages. Both operations are synchronous; control does not return to the 
client until the read or write is complete 

The area to or from which data is copied must be in mapped virtual memory, page aligned, 
and, if necessary, writable; otherwise, an address fault or write protect fault will result. If 
an attempt is made to read or write beyond the end of the floppy file, the error 
Error[endOfFile] is raised. If the file argument does not specify a known file on that floppy 
diskette, ErrorffileNotFound] is raised. If an attempt to write to the floppy fails because 
the write enable sticker has been removed, the error Error[writelnhibited] is raised. The 
error ErrorfhardwareError] is raised if the drive appears to be broken or has temporarily 
failed in an unexpected manner. 

If a read or write error occurs during transmission of the data (and the sector is not 
already recorded in badSectorTable), the signal DataError is raised and data transmission 
stops. This signal is raised after the data transmission occurs. The values returned with 
this signal indicate the offending file and page number and a pointer to the buffer in 
virtual memory containing the data read or written. The signal may not be resumed. 
Instead, the client should decide what to do with the bad data and bad sector, then 
continue its read or write operation 

Floppy.CopyFromPilotFile: procedure [pilotFile: File. File, floppyFiie: Fioppy.FileHandle, 
firstPilotPage: File. PageNumber, firstFloppyPage: Fioppy.PageNumber, 
count: Fioppy.PageCount <— Fioppy.defaultPageCount]; 

Fioppy.CopyToPilotFile: procedure [floppyFiie: Fioppy.FileHandle, pilotFile: File-File, 
firstFloppyPage: Fioppy.PageNumber, firstPilotPage: File.PageNumber, 
count: Fioppy.PageCount ^-Fioppy.defaultPageCount]; 

Fioppy.defaultPageCount: Fioppy.PageNumber = .. .; 

Fioppy.ErrorType: type = { ..., incompatibleSizes,.. .]; 

These two operations are simple extensions of Floppy. Read and Floppy.Write. They copy the 
specified file pages between a floppy disk file and a Pilot file. The specified pages must 
exist in both files or Floppy. ErrorfincompatibleSizes] will be raised. If count is specified as 
defaultPageCount then the entire file is copied starting from the specified page. Any of 
the errors mentioned above for the Read and Write functions may also be raised. Both 
operations are synchronous. 


5-22 




Pilot Programmer’s Manual 


5 


A bad sector on the floppy diskette may be replaced by an alternate sector somewhere else 
on the diskette by calling the following operation. 

Fioppy.ReplaceBadSector: procedure [file: Floppy. FileHandle, page: Fioppy.PageNumber] 
returns [readError: boolean]; 

This operation identifies a sector in terms of a page within a file and causes it to be 
marked bad. An alternate copy of the sector is placed somewhere else on the diskette. 
Pilot will do its best to copy the information from the bad sector to the alternate one. If 
data errors occur during this copy, the readError result of this procedure is TRUE. If, 
however, Pilot believes that it has made an exact copy, the result is false. After this 
operation completes, the client may overwrite the sector with any data via the operation 
Write. Bad sectors which have been replaced are invisible to client programs except for the 
performance of Pilot in accessing them (extra disk seeks are required and an access to a 
sequence of pages must be broken up). 

Caution: ReplaceBadSector is not implemented in Pilot 11.0. 

5.5.2 Snapshotting and replication of the floppy volume 

To facilitate easy snapshotting and replicating of floppies, the following procedures have 
been added 

Fioppy.PagesForlmage: procedure [floppyDrive: cardinal *-0] returns [File.pageCount]; 

Fioppy.Makeimage: procedure [ 

• floppyDrive: cardinal <-0, imageFile: File.File, 
firstlmagePage: File.PageNumber]; 

Fioppy.CreateFloppyFromlmage: procedure [ 
floppyDrive: cardinal *-0, imageFile: File. File, 
firstlmagePage: File.PageNumber, reformatFloppy: boolean, 
floppyDensity: Fioppy.Density default, floppySides: Fioppy.Sides default, 
numberOfFiles: cardinal <-0, newLabelString: long string «-nil]; 

Fioppy.Getl mage Attributes: procedure [ 

imageFile: File.File, firstlmagePage: File.PageNumber, 
name: long string nil] 
returns [ 

maxNumberOfFiles: cardinal, currentNumberOfFiles: cardinal, 
density: Fioppy.Density, sides: Fioppy.Sides]; 

Floppy. ErrorType: type * 

fileListLengthTooShort, floppylmagelnvalid, floppySpaceTooSmalL.}; 

PagesForlmage is used to determine the number of pages needed to copy the contents of a 
floppy to a file. 

The client calls Makelmage to snapshot a floppy. The call specifies the destination image 
file and the page of the destination file at which the image should begin. 

To create a floppy from an image file, the client calls CreateFloppyFromlmage specifying 
the drive to copy to, the image file to copy from, and various other parameters about the 
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floppy. The newLabelString parameter permits changing the floppy’s name from that in 
the image file. If reformatFloppy is true, the floppy is formatted. If the numberOfFiles is 
not zero, and the current number of files on the image file is greater than numberofFiles, 
then ErrorffileListLengthTooShort] is raised. Error[floppylmagelnvalid] is raised if the 
version, seal, or any of the file id’s on the image file are invalid. IfJ,he size of the image file 
is greater than the available space on the floppy, Error[floppySpaceTooSmall] is raised. 

Note: DataError may be raised by .Makelmage or .CreateFloppyFromlmage if a read or 
write error occurs during transmission of the data. 

Finally, the interface provides GetlmageAttributes so that the client can get information 
about the image stored in an image file. 


5.5.3 Managing the floppy volume 

The floppy diskette may be formatted using the following operation. The volume must not 
be open. 

Floppy.Format: procedure [drive: cardinal, maxNumberOfFileListEntries: cardinal, 
labelstring: long string, density: Fioppy.Density default, 
sides: Fioppy.Sides default]; 

Floppy. maxCharactersinLabel: cardinal * 40; 

Fioppy.Density: type * {single, double, default}; 

Fioppy.Sides: type = {one, two, default}; 

Floppy.ErrorType: type = {..., onlySingleDensity, onlyOneSide, badDisk,...}; 
Fioppy.AlreadyFormatted: signal [labelstring: long string]; 

This operation erases the diskette, writes all information according to the standard 
supported by Pilot, and creates an empty file list large enough to hold the number of 
entries specified. A label string is also written on the diskette, in the same way as label 
strings are written on Pilot rigid disk volumes. If the floppy is already formatted to be a 
Pilot floppy volume, the resumable signal AlreadyFormatted is raised. This gives the 
client a last chance to recover from accidentally formatting an already valuable floppy. 
The density and sides arguments give the client optional control over these attributes of 
the diskette when necessary for information interchange. The errors 
Error[onlySingleDensity] and Error[onlyOneSide] are raised if either the diskette or the 
drive imposes these limitations. The defaults of these cause Pilot to choose appropriate 
values for the drive and the diskette. If the disk cannot be formatted due to problems with 
either the diskette or the drive, Error[badDisk] is raised. 

Fioppy.GetAttributes: procedure [volume: Floppy. VolumeHandle, 
labelstring: long string] 

returns [freeSpace, largestBlock:pioppy.PageCount, fileList, rootFile: Floppy.FileHandle, 
density: Fioppy.Density, sides: Fioppy.Sides, maxFiieListEntries: cardinal]; 

Floppy.ErrorType: type = {..., stringTooShort,...}; 
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This operation gets relevant attributes about a floppy volume. The value of the label 
string is stored in the labelstring argument (except that a nil argument causes this to be 
bypassed, rather than raising an error). Other attributes are returned in the result list. 
The result freeSpace indicates the total number of free pages on the diskette, while the 
result largestBlock indicates the largest file that could be created without having to 
compact the diskette (see below). The density and sides attributes describe the diskette, 
independently of what the drive can support. The rootFile is a distinguished file identified 
by the client (see below). The fileList attribute describes the file list maintained by Pilot on 
the diskette. It is returned for completeness only; clients are strongly discouraged from 
using it. The maxFileListEntries attribute describes the length of the list. It is fixed at 
format time and does not change over the life of a floppy file system instance. 

A file may be created on the diskette with the following operation. 

Floppy.CreateFile: procedure [volume: Fioppy.VolumeHandle, size:Fioppy.PageCount, 
fileType: File.Type] 
returns [file: Fioppy.FileHandle]; 

Fioppy.ErrorType: type = {..., insufficientSpace, zeroSizeFile, fileListFull...}; 

This operation creates a file of the specified size on the diskette. As with files on the Pilot 
rigid disk, each file is created with a File. Type to allow the client program to distinguish 
what kind of file it is. All files are allocated contiguously on the diskette. If there is no 
block of free space large enough, Error[insufficientSpace] is raised. An attempt to created 
zero-sized file fails with the error ErrorfzeroSizeFile], If the file list is full, the file is not 
created and ErrorffileListFull] is raised This operation, including the updating of the file 
list, is synchronous and does not return to the client until the file is created and the 
diskette is well-formed in the new state 

Floppy.DeleteFile: procedure [file: Floppy. FileHandle]; 

This operation deletes the specified file and makes the space available for other files. This 
operation, including the updating of the file list, is synchronous and does not return to the 
client until the file is deleted and the diskette is well-formed in the new state. 

Floppy.GetFileAttributes: procedure [file: Fioppy.FileHandle] 
returns [size: Fioppy.PageCount, type: File. Type]; 

This operation gets the attributes of a file. 

Fioppy.GetNextFile: procedure [previousFile: Fioppy.FileHandle] 
returns [nextFile: Fioppy.FileHandle]; 

Floppy. nullFilelD: Floppy. FilelD = ...; 

This operation enumerates the files on a floppy volume in the standard style of a Pilot 
stateless enumerator. Files are enumerated in the order that they occur on the diskette. 
The enumeration is started by supplying the nullFilelD and the appropriate volume and it 
ends with the same value. The file list is not included in this enumeration. 

Fioppy.SetRootFile: procedure [file: Fioppy.FileHandle]; 
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This operation allows the client to record the FilelD of a file in the volume data structures 
for later use. This might be the pointer to a client level directory or to some other data 
structure. If the file does not exist, Error[fileNotFound] is raised. 

Fioppy.Compact: procedure [volume: Floppy. Volume]; 

This operation rearranges the files on the diskette so that all of the free space occurs in one 
block at the end of the volume This is necessary to recover fragmented space in those 
(rare) cases where a lot of file creation and deletion occurs. 

Caution: Compact is not implemented in Pilot 11.0 

Floppy. Scavenge: procedure [volume: Floppy. volume] 
returns [numberOfBadSectors: Floppy. PageCount]; 

Fioppy.GetNextBadSector: procedure [volume: Floppy. VolumeHandle, oldlndex: cardinal] 
returns [newlndex: cardinal, file: Floppy. FileHandle, page: Floppy. PageNumber]; 

The operation Scavenge recovers the contents of a malformed floppy by restoring the file 
list, repairing bad marker pages, and recovering other data specified by the Pilot floppy 
standard. Scavenge returns the number of new bad pages it encountered in client files 
while scavenging (others can be handled by Pilot automatically). The operation 
GetNextBadSector allows the client to enumerate the new bad sectors, starting and 
ending with an index of zero. 

Caution: Scavenge and GetNextBadSector are not implemented inPilot 11.0. 

FloppyExtras. Erase: PROCEDURE [ 

drive: cardinal, maxNumberOfFileListEntries: cardinal, 
labelstring: long string nil]; 

FloppyExtras. ExtrasErrorType: type = notFormatted, 

The operation Erase resets all the floppy file system data structures, writes a new clean 
file list, re-marks bad pages, and resets all file and microcode pointers. It does not erase 
any data sectors (only Format will actually erase all sectors on the diskette) If a 
labelstring is specified, it replaces the current label; otherwise the current label remains 
unchanged. The volume will be closed if it is open. If drive does not describe a drive 
currently in the system, Floppy. Error[noSuchDrive] is raised. If the length of labelstring 
exceeds Floppy. maxCharactersInLabel, the label will be truncated to the maximum length. 
Floppy. Error[badDi$k] is raised if the disk cannot be accessed Floppy. ErrorfnotReady] is 
raised if there is no diskette in the drive or the drive is not ready. If the diskette is write 
protected, Floppy. Errorfwritelnhibited] is raised. FloppyExtras. ExtrasErrorfnotFormatted] is 
raised if the diskette has invalid formatting information. 

FioppyExtras.NewScavenge: public procedure [drive: cardinal] 
returns [okay: boolean]; 

FioppyExtras.ExtrasErrorType: type = {..., volumeOpen,...}; 

The operation NewScavenge recovers the contents of a malformed floppy by restoring the 
file list, repairing bad marker pages, and recovering other data specified by the Pilot 
floppy standard. The volume must not be open. The return value okay indicates whether 
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the scavenge was successful: if okay returns TRUE, the floppy was, or was made, consistent. 
If drive does not describe a drive currently in the system, Floppy.Error[noSuchDrive] is 
raised. If the diskette is write protected, Floppy. Errorfwritelnhibited] is raised. 
FloppyExtras.ExtrasError[volumeOpen] is raised if the floppy volume on the diskette is open. 
Other Floppy.Errors which result from reading or writing the floppy may also be raised. 

Note: The 12.0 floppy scavenger does not repair damage. After validating the file system 
and internal data structures, it resets the "needs-scavenging" indicator if the floppy is 
consistent. 

Note: In a future release, Floppy Extras and FloppyExtras.Extras will be merged into Floppy. At 
that time, the names of some interface items may change. 

Several special operations are necessary to support Pilot-bootable floppies: 

Fioppy.CreatelnitialMicrocodeFile: procedure [volume: Floppy. VolumeHandle, 
size: Fioppy.pageCount, type: File.Type, 
startingPageNumber: Floppy.PageNumber 1] 

returns [file: Floppy.FileHandle]; 

Floppy. ErrorType: type = {... , initialMicrocodeSpaceNotAvailable, badSectors,.. 

This operation is like CreateFile except that it creates the initial microcode file at the exact 
location demanded by the hardware boot facility. In particular, the page of the file 
numbered StartingPageNumber will appear where the hardware expects to read the first 
block from the floppy diskette at boot time. The hardware of our current machines 
demands that the initial microcode file must be contiguous and contain no bad sectors. 
Thus, CreatelnitialMicrocodeFile should normally be applied only to a clean, newly 
formatted diskette. If it is not possible to create such a file, either because there already is 
a file there or because some sector is bad, Floppy. Error[initialMicrocodeSpaceNotAvailable] 
or Floppy.Error[badSectors] are raised 

Floppy.nullBootFilePointer: Floppy.BootFilePointer = [nullFilelD, 0]; 

Floppy. SetBootFiles: procedure [vol: Floppy. VolumeHandle, 
pilotMicrocode, diagnosticMicrocode, germ, 
pilotBootFile: Floppy. BootFilePointerFloppy.nullBootFilePointer]; 

Floppy. GetBootFiles: procedure [volume: Floppy. VolumeHandle] 

returns [initialMicrocode, pilotMicrocode, diagnosticMicrocode, germ, 
pilotBootFile: Floppy .BootFilePointer]; 

Floppy. BootFilePointer: type = record [Floppy. FilelD, page: Floppy. pageNumber]; 

Floppy. ErrorType: type « { ..., invalidPageNumber,... }; 

The operation SetBootFiles sets the pointers to the relevant boot files in the volume data 
structures. This track is read by the initial microcode at boot time in order to properly 
initialize the microcode and Pilot. Both a FilelD and a page number are specified so that 
leader pages may be included in floppy boot files if desired. SetBootFiles will set the 
pointer in track zero for any of its arguments with a non-null FilelD. Boot fife pointers with 
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nullFilelD are cleared. This operation is synchronous. If the specified file page(s) do not 
exist, the error Error[invalidPageNumber] is raised. 

The remaining boot files on the diskette, apart from the initial microcode boot file, are all 
read by the initial microcode file. Thus, they can be located anywhere and can have bad 
sectors in them, and the initial microcode can interpret the bad sector table if necessary. 

The operation GetBootFiles gets the pointers to all of the boot files, including the initial 
microcode boot file. 

It is recommended that clients assign distinguished Pilot file types to boot files to allow 
the boot file pointers to be reset, if necessary, after scavenging. 

Note: Booting in the manner described here is not supported by Pilot 11.0. Clients must 
use MakeDLionBootFloppy tool to create bootable floppies in Pilot 11.0. 

5-6 TTY Port channel 

TTYPort: definitions 
TTYPortEnvironment: definitions 

The TTY Port channel is a Product Common Software package which provides a Pilot 
client with access to the TTY Port controller and the connected device. It contains 
procedures for sending and receiving bytes to and from the device, and for receiving status 
back. Examples of devices that use the TTY Port include the Diablo 630 character printer 
and the Lear Siegler ADM-3 display terminal The TTYPort interface is implemented by 
TTYPortChannel.bed 


The Diablo 630 character printer is an ASCII output device containing a daisy wheel 
printer of the HyType II genre. The Lear Siegler ADM-3 display terminal is an ASCII I/O 
device of the "glass teletype" type. 

5.6.1 Creating and deleting the TTY Port channel 

TTYPort.Create: procedure [lineNumber: cardinal] 
returns [TTYPort.ChannelHandle]; 

TTYPort.ChannelHandle: private ...; 

TTYPort.nullChannelHandle: TTYPort.ChannelHandle ...; 

TTYPort.ChannelAlreadyExists. error; 

TTYPort.NoTTYPortHardware: error; 

TTYPort.InvalidLineNumber: error; 

Create creates the channel to the TTY Port. If the channel already exists, Create 
generates the error TTYPort.ChannelAlreadyExists. If no TTY Port hardware is installed, 
Create generates the error TTYPort.NoTTYPortHardware. If lineNumber does not represent 
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a line present on the TTY Port controller, Create generates the error 

TTYPort. InvalidLineNumber. 

TTYPort. Delete: procedure [channel: TTYPort.ChannelHandle]; 

Delete deletes the channel and releases the associated device. This operation has the 
effect of calling Quiesce, aborting all pending activity on the channel. Any uncompleted 
Gets or Puts will be terminated with status = abortedByDelete 

TTYPort.Quiesce: procedure [channel: TTYPort.ChannelHandle], 

Quiesce aborts all pending activity. All uncompleted asynchronous activities (i.e., those 
initiated by Get or Put) will be terminated with status equal to aborted. Any additional 
operations on the channel, other than Delete, cause the error ChannelQuiesced. 

5.6.2 Data transfer 

TTYPort. Put: procedure [channel: TTYPort.ChannelHandle,data: character] 
returns [status: TTYPort.TransferStatus]; 

Put transmits data to the TTY Port status will he set to success if the character is 
successfully transmitted. Aborts are disabled for this operation. 

TTYPort.Get: procedure [channel: TTYPort.ChannelHandle] 
returns [data: character, status: TTYPort TransferStatus]; 

TTYPort.Get waits until a byte of data is received from the TTY Port, status equals success 
if a character is successfully received. Aborts are disabled for this operation. 

The procedure 

TTYPort.SendBreak: procedure [channel: TTYPort.ChannelHandle]; 

causes a break to be sent on the specified TTY channel. 

5.6.3 Data transfer status 

The status of an individual data transfer (i.e., Get or Put) is indicated by a variable of type 

TransferStatus. 

TTYPort.TransferStatus: type = {success, parityError, asynchFramingError, dataLost, 
breakDetected, aborted, abortedByDelete}, 

The meanings of these status codes are: 

success Normal completion. 

parityError Data has not been transferred faithfully. 

asynchFramingError Data has not been transferred faithfully (i.e., stop bits 

were missing) 


5-29 




5 


I/O Devices 


dataLost 


Data has been lost due to lack of any data buffers to hold 
received characters. 


break Detected 


aborted 


abortedByDelete 


A break has occurred on the line. This bit is latched and 
can be cleared using the SetParameter operation (see 
below). 

TTYPort. Quiesce has been called while the transfer is 
outstanding. 

TTYPort. Delete has been called while the transfer is 
outstanding. 


5.6.4 TTY Port operations 

The TTY Port Channel will buffer up to 16 characters of input from its device along with 

their associated transfer status To see if and how much data has been received from the 

device by the TTY Port, call the procedure 

TTYPort.CharsAvailable: procedure [channel: TTYPort.ChannelHandle] 
returns [number: cardinal]; 

number indicates the number of input buffers containing data 

The various parameters associated with a TTY port are set with the procedure 

TTYPort.SetParameter: procedure [channel: TTYPort.ChannelHandle. 
parameter: TTYPort.Parameter]; 

The parameters are contained in records of the following type: 

TTYPort.Parameter: type = record [select parameter: * from 
hreakDetectedClear = > [breakDetectedClear: boolean], 
characterLength a > [characterLength: TTYPort.CharacterLength], 
clearToSend * > [clearToSend: boolean], 
dataSetReady = > [dataSetReady: boolean], 
lineSpeed = > [lineSpeed: TTYPort.LineSpeed], 
parity * > [parity: TTYPort Parity], 
stopBits = > [stopBits: TTYPort StopBits], 
endcase], 

TTYPort.CharacterLength: type = TTYPortEnvironment CharacterLength; 

TTYPort.LineSpeed: TYPE = TTYPortEnvironment.LineSpeed; 

TTYPort.Parity: TYPE = TTYPortEnvironment. Parity; 

TTYPort. StopBits: TYPE = TTYPortEnvironment. StopBits; 

TTYPortEnvironment.LineSpeed: type = {bps50, bps75, bpsllO, bps134p5, bps150, bps300, 

, bps600, bps1200, bps1800, bps2000, bps2400, bps3600, bps4800, bps7200, bps9600, 
bps19200}; 
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TTYPortEnvironment. Parity: type = {none, odd, even}; 

TTYPortEnvironment.CharacterLength: type = {Iengthls5bits, Iengthls6bits, Iengthls7bits, 
Iengthls8bits}; 

TTYPortEnvironment.StopBits: type = {none, one, oneAndHalf, two}; 

breakOetectedClear is used to clear the latch bit breakDetected in TTYPort.DeviceStatus 

CharacterLength selects the character length and is defaulted to Iengthls8bits. 

The boolean clearToSend governs the state of the corresponding circuit to the TTY Port. It 
is defaulted to false. After the TTY Port channel is created, clearToSend should remain 
TRUE at all times since the communication line is full-duplex. 

The boolean dataSetReady governs the state of the corresponding circuit to the TTY Port. 
It is defaulted to false dataSetReady should be set true when the communication line is 
to be connected, false when it is to be disconnected. 

TTYPort.LineSpeed selects the timer constant for the baud rate generator which provides 
the clocking for transmissions to and from the TTY Port. bps1200 is the default. 

TTYPort. Parity selects the parity of the transmissions none is the default. 

TTYPort.StOpBits is the number of stop bits, two is the default. 

5*6.5 Device status 

In addition to the status information returned for each data transfer operation, state 
information about the TTY Port itself is kept in the DeviceStatus record. It is accessed via 
the GetStatus procedure. 

TTYPort. GetStatus: procedure [channel: TTYPort. ChannelHandle] 
returns [stat: TTYPort DeviceStatus]; 

The procedure 

TTYPort.StatusWait: procedure [channel: TTYPort.ChannelHandle, 
stat: TTYPort.DeviceStatus] 
returns [newstat: TTYPort.DeviceStatus]; 

waits until the current DeviceStatus differs from the supplied parameter stat. The client 
must examine newstat to determine what action to take. 

TTYPort.DeviceStatus: type = record [aborted, breakDetected, dataTerminalReady, 
readyToGet, readyToPut, requestToSend: boolean]; 

The boolean aborted indicates that the TTYPort.StatusWait was aborted by either a 

TTYPort.Delete or TTYPort.Quiesce. 

The boolean breakDetected indicates that a "break” was received on the communication 
line, where "break" is defined to be the absence of a "stop" bit for more than 190 
milliseconds. This boolean is called a latch bit in that it is set by the channel when the 


5-31 




5 


I/O Devices 


associated condition occurs, but is not cleared by the channel when the condition clears. It 
remains set to guarantee that the client has an opportunity to observe it. To clear it (in 
order to detect its subsequent setting), breakDetectedClear is specified as a parameter to 

the TTYPort.SetParameter procedure 

The boolean dataTerminalReady is true when the associated device is powered on. 

The boolean readyToGet is true when the hardware input buffer (for data sent from the 
device) is not empty. 

The boolean readyToPut is true when the hardware output buffer (for data sent to the 
device) is not full. 

The boolean requestToSend is held true by the device (as in a 103-type modem) to enable 
transmission to the device. 


5.7 TTY Input/Output 

TTY: DEFINITIONS ...; 

The TTY interface provides a simple character-oriented input and output facility. It 
admits many implementations on character-oriented terminal devices. In this way it is a 
lot like the Stream interface This interface is Product Common Software. 

Note: For most clients, the default TTY implementation will be supplied as part of this 
release: TTYLearSiegler.bcd or that provided by the Mesa Development Environment. 

Note: The Lear Siegler TTY implementation has the following default settings for the 
TTY Port channel: 8 bit characters, 9600 baud, 2 stop bits, no parity, CTS set to ON, and 
DSR set to ON. 


5.7.1 Starting and stopping 

tty. Create: procedure [name: long string nil, 
backingStream, ttylmpl: stream. Handle nil] 
returns [h: tty Handle]; 

tty. Handle: type [2]; 

tty. nullHandle: tty. Handle = loophole[last[longcardinal]; 

TTY.NoDefaultlnstance: error; 
m.OutOflnstances: error; 

Create creates a Handle, which is returned to the caller. This handle is then passed as an 
argument to the other TTY input/output operations. The arguments name and 
backingStream are used by the underlying TTY implementation in an implementation- 
dependent fashion to implement the backing file for the TTY, If ttylmpl is not nil, it is 
used as the stream implementing the TTY stream If ttylmpl is nil, an instance of the 
default TTY implementation is created The parameter h is the tty. Handle that will 
correspond to the stream underlying this TTY channel when the call to TTY. Create 
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completes. If there is no default TTY implementation, the error NoDefaultlnstance is 
raised. If another Handle cannot be created, OutOflnstances is raised. 

TTY.SetBackingSize: procedure [h: tty. Handle, size: long cardinal]; 

This procedure sets an upper limit on the number of bytes in the backing file and forces 
the backing file to be used in a wraparound mode. It has no effect if the implementation 
does not support a backing file. 

tty. Destroy: procedure [h: tty. Handle, deleteBackingFile: boolean false]; 

Destroy invalidates tty. Handle. If deleteBackingFile is true and the backing file was 
created by Create then the backing file is deleted 

TTY.UserAbort: procedure^: tty. Handle] returns [yes: boolean]; 

TTY.ResetUserAbort: PROCEDUREfh: TTY.Handle]; 

tty.S etUserAbort: procedure^: TTY.Handle]; 

UserAbort returns the value of the user abort flag, true indicates that that user has typed 
some "abort** key. TTY.ResetUserAbort clears the user abort flag tty SetUserAbort sets 
the user abort flag, just as if the user had typed the "abort" key. 

Note: The Lear Siegler TTY implementation allows users to abort processes by 
depressing the Break key or by depressing the Control and Stop keys simultaneously. 

5*7.2 Signals and errors 
The signal 

TTY.LineOverflow: signal [s: long string] returns [ns: long string]; 

indicates that input has filled the string s. The current contents of the string are passed as 
a parameter. The catch phrase should return a string ns with more room 

The signal 

TTY.RubOUt: SIGNAL; 

indicates that the DEL key was typed during TTY GetEditedString (or procedures which call 

GetEditedString. 

5.7.3 Output 

To output a block of characters call 

TTY.PutBlock: PROCEDUREfh: TTY.Handle, block: Environment. Block]; 
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5.7.4 Utilities 

TTY.BackingStream: procedure [h: tty Handle] returns [stream: stream. Handle]; 
TTY.NoBackingFile: error; 

If a backing stream was created by TTY, Create, this operation returns the Stream. Handle for 
it. If none was created, the error TTY.NoBackingFile is raised 

TTY.CharsAvailable: procedure [h: tty Handle] returns [number: cardinal]; 

CharsAvailable returns the number of input characters available (but not yet delivered to 
the client). 

TTY.NewLine: procedure [h: tty Handle] returns [yes: boolean]; 

NewLine returns true when at the beginning of an output line This procedure is mainly 
used when formatting output. 

TTY.PutBackChar: procedure [h: tty. Handle, c: character]; 

PutBackChar places c at the front of the list of characters to be input to the client. 

TTY.SetEcho: procedure [h: tty. Handle, new: TTY.EchoClass] 
returns [old: TTY.EchoClass]; 

TTY.GetEcho: procedure [h: tty. Handle returns [old: TTY.EchoClass]; 

TTY.EchoClass: type » {none, plain, stars}; 

SetEcho sets how input characters are to be echoed back to the output. It returns the 
previous state of the echoing mode If the mode is none, no characters are echoed: if it is 
stars, the character is echoed for each input character. The default echoing mode is 
plain. Automatic echoing is done only for the procedure TTY.GetEditedString and the 
procedures implemented using TTY.GetEditedString. 

TTY.BIinkDisplay: procedure [h: tty Handle]; 

This procedure causes the display to be blinked if the device is capable of it. 

TTY.PushAlternatelnputStream: procedure [h: tty. Handle, stream: stream. Handle]; 

TTY.PopAlternatelnputStreams: procedure [h: tty. Handle, howMany: cardinal*-1]; 

PushAlternatelnputStream adds an alternate input stream to the Handle. Characters will 
be taken from the most recently pushed alternate input stream until it is exhausted, at 
which point characters will be taken from the previous input stream 
PopAlternatelnputStreams removes howMany alternate input streams from the Handle 
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If howmany is greater than the number of existing alternate input streams, all existing 
are removed before PopAlternatelnputStream returns. 

5.7.5 String input operations 

The operation 

TTY.GetChar: procedure [h: tty. Handle] returns [c: character]; 

returns the next character of input when it becomes available. 

TTY.CharStatus: type = {ok, stop, ignore}; 

TTY.GetEditedString: procedure [h: tty Handle, s: long string, 
t: procedure [c: character] returns [status: TTY.CharStatus] ] 

RETURNS [c: character]; 

GetEditedString appends input charaeter(s) to the string s. The user-supplied procedure t 
determines which character terminates the string If t returns stop, the character c 
passed to it should terminate the string If t returns ok, the character c should be 
appended to the string. If t returns ignore, the character c should not be appended to the 
string, but the string should not yet be terminated. Note that the client must initialize 
s.length, typically to zero The signal tty LineOverflow is raised if s.maxlength is 
reached The following special characters are recognized on input, and are not appended 
tos: 



DEL 

raises the signal TTY.Rubout 

50H,BS 

fA, | H (backspace) - 

delete the last character 

ETB, DC1 

■f W, | Q (backword) - 

delete the last word 

CAN 

t x 

delete everything 

DC2 

f R 

retype the line 

SYN 

t V 

quote the next character, used to input 
special characters 


Echoing of characters other than the special characters and the terminating character is 
determined by the echoing mode set by TTY.SetEcho (default is plain). The returned 
character c is the character which terminated the string, c is not echoed nor included in 
the string. 

The following three string input procedures use TTY.GetEditedString to read a string. 

m.GetString: procedure [h: tty Handle, s: long string, 

t: procedure [c: character] returns [status: TTY.CharStatus]]; 
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TTY.GetID: procedure [h: tty. Handle, s: long string]; 
m.GetLine: procedure [h: tty. Handle, s: long string]; 

GetString reads a string into s. The user-supplied procedure t determines which character 
terminates the string. If t returns stop, the character c passed to it terminates the string. 
If t returns ok, the character c will be appended to the string. If t returns ignore, the 
character c will not be appended to the string, but the string will not yet be terminated. 
The terminating character (the character returned by TTY.GetEditedString) is echoed 
regardless of the echoing mode. 

GetID reads a string terminated with a space or a carriage return into s. The terminating 
character (space or carriage return) is not echoed regardless of the echoing mode. 

GetLine reads a string terminated with a carriage return into s The carriage return is not 
appended to s. A carriage return is output regardless of the echoing mode. 

The procedure 

TTY.GetPassword: procedure [h: tty. Handle, s: long string]; 

calls GetEditedString with echoing set to stars, then restores the previous echoing mode. 

5.7.6 String output operations 

The operation 

TTY.PutChar: procedure [h: tty Handle,c: character]; 

outputs the character c If c is a carriage return, the next character that is output will be 
in the first position of the next line. Note that control characters other than a carriage 
return being output are not interpreted by PutChar, but rather translated into a two 
character printable sequence (e g , f A). If c is Ascii. BS, a representation of the backspace 
will be displayed in the window. To backspace over previously output characters, see 
RemoveCharacter below. 

TTY.PutCR: procedure [h: tty.H andle]; 

PutCR outputs a carriage return. The next character that is output will be in the first 
position of the next line. 

TTY.PutBlank, PutBlanks: procedure [h: tty Handle, n: cardinal 1]; 

PutBlank(s) outputs n spaces. 

m.PutDate: procedure [h: tty. Handle,gmt: Time. Packed, 
format: TTY.DateFormat noSeconds]; 

TTY.DateFormat: type = Format DateFormat; 

Format. DateFormat: type = {dateOnly, noSeconds, datelime, full, mailDate}; 
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PutDate outputs the Greenwich mean time, packed in the Time format, according to the 
format specified. 


The different formats have the following interpretation: 
maildate: 27 Jul 83 09:23:29 PDT (Wednesday) 

full: 27-Jul-83 9:23 29 PDT 

dateTime: 27-Jui-83 9:23 29 

noSeconds: 27-Jul-83 9:23 

dateOnly: 27-Jul-83 

TTY.PutString, PutText procedure [h: tty Handle, s: long string]; 

TTY.PutLine: procedure [h: tty Handle, s: long string]; 


TTY.PutSubString, PutLongSubString: procedure [h: tty Handle, 
ss: String.SubString]; 

PutString outputs the string s. Whenever a carriage return is output, the next character 
that is output will be in the first position of the next line. PutLine outputs the string s 
followed by a carriage return. The other procedures output their string parameter 

The procedures 

TTY.RemoveCharacter, RemoveCharacters: procedure [h: tty Handle, 
n: cardinal «-1]; 

backspaces over the last n characters output, erasing the characters from the display In 
implementations lacking an actual hardware backspace facility, this is often simulated by 
outputting the backed-over text surrounded by backslashes 


5.7.7 Numeric input operations 

The following six numeric input procedures use tty GetEditedString to read a string 
terminated with a space or a carriage return. The terminating character is not echoed 
(regardless of the echoing mode). An implementation of tty might use the numeric 
conversion facilities offered by the String interface. if it did, it would raise 
String.InvalidNumber when presented with an input string that did not conform to the 
syntax for a number. 

TTY.GetNumber: procedure [h: tty Handle, default: unspecified, 
radix: cardinal, showDefault: boolean] 
returns [n: unspecified]; 

TTY.GetLongNumber: procedure [ h: tty. Handle, default: long unspecified, radix: cardinal, 
showDefault: boolean] 
returns [n: long unspecified]; 

These operations read in a string and convert it to base radix. If an" ESC is the first 
character typed and showDefault is true, a string representing the value of default 
converted to base radix is displayed if radix is 10 and default is negative, a minus sign 
will be prefixed, or if radix is 8, the character B will be postfixed. 
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TTY.GetOctal: procedure [h: tty. Handle] returns [n: unspecified]; 

TTY.GetLongOctal: procedure [h: tty. Handle] returns [n: long unspecified]; 

TTY.GetDecimal: procedure [h: tty. Handle] returns [n: integer]; 

TTY.GetLongDecimal: procedure [h: tty. Handle] returns [n: long integer]; 

GetOctal and GetLongOctal read in a string then convert it to octal. GetDecima! and 
GetLongDecimal read in a string then convert it to decimal. 


5.7.8 Numeric output operations 

m.PutNumber: procedure [ h: tty Handle, n: unspecified, 
format: TTY.NumberFormat]; 

TTY.PutLongNumber: procedure [ h: tty Handle, n: long unspecified, 
format: TTY.NumberFormat]; 

TTY.NumberFormat: type = Format NumberFormat; 

Format. NumberFormat: type = record [base: [2..36] <—10, zerofill: boolean «-false, 
unsigned: boolean «-true, columns: [0..255] <— 0] ; 

PutNumber and PutLongNumber convert n to a string representing its value according to 
the format specified, and then output the string. NumberFormat refers to a number whose 
base is base. The field is columns wide (if columns is 0, it means use as many as needed). 
If zerofill is TRUE, the extra columns are filled with zeros, otherwise spaces are used If 
unsigned is TRUE, the number is treated as unsigned. Output strings representing 
negative numbers begin with a minus sign. 

TTY.PutOctal: procedure [h: tty. Handle, n: unspecified]; 

TTY.PutLongOctal: procedure [h: tty. Handle, n: long unspecified]; 

m.PutDecimal: procedure [h; tty. Handle, n: integer]; 

TTY.PutLongDecimal: procedure [h; tty Handle, n: long integer]; 

PutOctal and PutLongOctal convert n to a string representing the octal value (when n is 
greater than 7, the character R is appended), and then output the string. PutDecimal and 
PutLongDecimal convert n to a string representing the signed decimal value, and then 
output the string. 
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The communication package provides Pilot clients the facility to perform inter- and intra- 
processor communication at a relatively high level. The structure of Pilot communications 
is layered. That layering follows closely the protocol levels specified in Internet 
Transport Protocols, XSIS 028112, dated December, 1981 (XNS). 

Only the lowest level protocol layer, level 0, is medium dependent. The only medium 
supported by Pilot communications is the ethernet. Level 0 does provide the framework 
that permits Pilot clients to implement other level 0 drivers. It is assumed that all level 0 
drivers will provide at least the following features: immediate destination addressing, 
data checking (CRC, LRC, etc), the ability to transmit any 8-bit data pattern, and a means 
of detecting physical message length. 

The level 1 communication layer, known as the Internet Datagram Protocol (IDP), is 
medium independent. Access to this layer is via sockets . A socket is a logical input/output 
resource modeled after the Pilot software channel. A socket is an address within a 
machine, identified by a 16-bit number, to which NS packets (henceforth referred to as 
packets) can be delivered and from which packets may be transmitted. Any number of 
unique addresses may coexist in the same machine. 

The socket facility enables reception and transmission of packets per the conventions of 
IDP. At this level packets are delivered with only some high probability. Packets may 
arrive out of order, may be duplicated, or may never arrive. The socket facility is used 
internally in the implementation of higher-level communication facilities, and is not itself 
available to Pilot clients. 

Packets may be transmitted or received over one of the ethernet local networks connected 
to the machine, or over any other communication media that is part of the NS 
communication system. Packets have an advisable maximum internetwork length of 576 
bytes in order to be forwardable by internetwork routers. 

The full source or destination address of packets is a System. Net work Address. Addresses 
are the concatenation of the host's network number (System. NetworkNumber), the host 
number (System. HostNumber) and a socket number (System. SocketNumber). Source 
addresses include an internally generated unique socket. Initial contact with remote 
machines requires knowing the full address of that machine. The network and host 
numbers are usually obtained from a central name to address translation facility 
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0 clearinghouse) and the socket is well known . Socket numbers in the range [0..2048) are 
reserved for well known sockets. 

Communication over the ethernet local network, or any communication network, is 
different from most other devices since the network may deliver an unsolicited packet 
which is destined for a socket. Such packets typically consume communication buffers, 
which are a critical resource. If the arrival rate of packets is high, the client is advised to 
perform a sufficient number of receive operations to provide adequate buffering. Incoming 
packets will never be queued for a particular socket if that socket does not exist. 

The sections on PacketExchange and NetworkStream describe interfaces to higher-level, more 
reliable protocols. The implementations of these interfaces are clients of the socket 
facility. These two interfaces supply the facilities to be used for NS communication 
applications. These two implementations make use of the error protocol which is not 
directly accessible to Pilot clients but is alluded to in some of the signal status codes. They 
also use the routing protocol. Client access to routing is described in the section on Router. 

6.1 Well known sockets 

NSConstants: definitions * ...; 

As mentioned, a portion of the socket number name space is reserved for use as well known 
sockets. Network addresses containing well known sockets are used to contact remote 
machines for the purpose of, or in absence of, arbitration for a unique network address. 

For example, to echo to a remote machine, a client would specify the remote machine’s 
address including the well known socket NSConstants.echoerSocket. The echo protocol is not 
a connection oriented protocol, therefore it does not require arbitration for a unique 
remote address. 

In the case of the sequence packet protocol, listeners are created using well known sockets 
and machines contact them by sending packets to that well known socket. But the 
protocol’s connection establishment procedures permit and encourage establishing the 
connection using a unique address, not consuming the well known socket. 

Note: A socket number assigned from outside the well known socket number range and 
then made known to one or more agents does become well known to those agents. The 
conveyance of that information should be considered a form of arbitration, regardless of 
how it is done. 

The following well known sockets have been assigned for specific purposes and are defined 
in the interface NSConstants. Clients should not use the listed socket number values 
except for the purpose indicated by their name. Applications that require well known 
sockets should pick an unassigned value and make it known so that use can be properly 
registered. 

unknownSocketID: System. SocketNumber = ... 
uniqueSocketID: System. SocketNumber a ... 
routinglnformationSocket: System. SocketNumber a ... 
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echoerSocket: System.SocketNumber a ... 
errorSocket: System.SocketNumber a ... 
envoySocket: System.SocketNumber a ... 
courierSocket: System.SocketNumber a ... 
x860ToFileServer: System.SocketNumber a ... 
dearingHouseSocket: System.SocketNumber a ... 
timeServerSocket: System.SocketNumber a ... 
pupAddressTranslation: System.SocketNumber a ... 
bootServerSocket: System.SocketNumber a ... 
ubIPCSocket: System.SocketNumber a ... 
ubBootServerSocket: System.SocketNumber a ... 
ubBootServeeSocket: System.SocketNumber a ... 
diagnosticsServerSocket: System.SocketNumber a ... 
newClearinghouseSocket: System.SocketNumber .a ... 
electronicMailFirstSocket: System.SocketNumber = ... 
electronicMailLastSocket: System.SocketNumber a ... 
etherBooteeFirstSocket: System.SocketNumber a ... 
etherBootGermSocket: System.SocketNumber a ... 
etherBooteeLastSocket: System.SocketNumber a ... 
voyeurSocket: System.SocketNumber a ... 
netManagementSocket: System.SocketNumber a ... 
teleOebugSocket: System.SocketNumber a ... 
galaxySocket: System.SocketNumber a ... 
protocolCertificationControl: System.SocketNumber a ... 
protocolCertific'ationTest: System.SocketNumber a ... 
outsideXeroxFirstSocket: System.SocketNumber a ... 
outsideXeroxLastSocket: System.SocketNumber a ... 
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maxWellKnownSocket: System. SocketNumber = ... 

NSConstantsExtras: definitions = ... 

authenticationlnfoSocket: System.SocketNumber ■ ... 
mailGatewaySocket: System.SocketNumber - ... 
netExecSocket: System.SocketNumber - ... 
wsInfoSocket: System.SocketNumber * ... 
mazeSocket: System.SocketNumber = ... 
pcRoutingTestSocket: System.SocketNumber a ... 
maxWellKnownSocket: System.SocketNumber = ... 

6c2 Packet exchange 

PacketExchange: definitions = 

PacketExchange is an interface to an implementation of the Packet Exchange Protocol - a 
level 2 Network Services Communication Protocol which is defined in Xerox Internet 
Transport Protocols . In contrast to NetworkStream, the PacketExchange interface provides 
access to a less reliable, connectionless protocol. The protocol is "single packet" oriented 
for simplicity, yet includes retransmitting and duplicate suppression for reliability. 
PacketExchange is suitable for applications where a single packet request is immediately 
followed by a single packet response that is the result of an idempotent operation, or where 
the communicating clients are capable of providing the necessary level of reliability 
through the very nature of their interaction. 

PacketExchange is implemented by the object file Commun ic a tion.bed. 

Packet Exchange Protocol packets may be sourced from and destined to any socket. While 
there is no connection established between PacketExchange correspondents, it is helpful to 
think of the entities that participate in the protocol in terms of a requestor and replier . A 
replier provides a service (or is a service agent), listening for PacketExchange packets from 
requestors. A requestor uses a service by sending requests to a replier. There is minimal 
state maintained by each end, only enough to remember local network addresses and to 
handle retransmissions and duplicates. 

Note: Due to the constant timeout-retransmission mechanism being used currently, 
PacketExchange is best suited for local network communication. In the future, end-to-end 
delays will be used for deriving retransmission timeouts, and internetwork link 
utilization should improve. 

Caution: PacketExchange is best applied to idempotent operations. This is due to the 
unreliable nature of the delivery of the reply and the inability to correctly process 
duplicate requests within the framework of the protocol. 
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6.2.1 Types and constants 

PacketExchange. ExchangeCIientType: type = machine dependent { 

unspecif ied(O), ti meService(1), cleari nghouseService(2), teledebug(1 OB), 
electronicMailFirstPEType(20B), electronicMailLastPEType(27B), 
remoteDebugFirstPEType(30B), remoteDebugLastPEType(37B), 
acceptanceTestRegistraticn(40B), performanceTestData(41 B), 
protocolCertification(50B), voyeur(51B), dixieDataPEType(IOIB), 
dixieAckPEType(102B), dixieBusyPEType(103B), dixieErrorPEType{104B), 
outsideXeroxFirst(IOOOOOB), outsideXeroxLast(LAST[cARDiNAu])}; 

The ExchangeCIientType defines well known exchange types that may be used for filtering 
requests or multiplexing within a service. 

PacketExchange.ExchangelD: TYPE a MACHINE DEPENDENT RECORD [a, b; WORD]; 

An exchange identifier is assigned to every request. This may be used by replying clients 
to suppress duplicate requests and is used by the requesting code to identify replies. The 
field will contain a value that is unique for each request using a function that has a period 
at least as long as the advertised maximum packet lifetime (60 seconds). The semantics of 
the ExchangelD are not sufficient to warrant the field's use as a request sequence. 

PacketExchange.ExchangeHandle: type [2]; 

PacketExchange. nullExchangeHandle: readonly PacketExchange.ExchangeHandle; 

An exchange handle is the result of one of PacketExchange's create routines and used as a 
parameter in other procedures. nullExchangeHandle may be used to indicate no valid 
exchange handle exists. 

PacketExchange.RequeStHandle: TYPE = LONG POINTER TO READONLY 
PacketExchange.RequestObject; 

PacketExchange. RequestO bj ect: TYPE = RECORD [ 

n Bytes: cardinal, 

requestType: PacketExchange. ExchangeCIientType, 
requestorsExchangelD: PacketExchange.ExchangelD, 
requestorsAddress: System.NetworkAddress]; 

A request handle is the result of a PacketExchange.WaitForRequest and is used as an 
argument in PacketExchange.SendReply. Through the request handle the client can get at 
some information about the request that is not included in the client data block. The fields 
addressed by the request handle may not be modified. A request handle must be discarded 
after the call to PacketExchange.SendReply. 

PacketExchange. WaitTime: TYPE = LONG CARDINAL; 

PacketExchange. defaultWaitTime: PacketExchange. WaitTime = 60000; 

PacketExchange.defaultRetransmissionlnterval: PacketExchange.WaitTime = 30000; 
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PacketExchange.WaitTime is a time used in all references having to do with setting wait 
times in either the requestor or replier. The time specified is always in milliseconds and 
will be converted to an internal representation before being used. If the conversion leads to 
overflow, an infinite wait time will be used. Due to the possibility of overflow, clients 
should be cautious attempting to time intervals greater than approximately 40 minutes. A 
wait time of zero will be interpreted as an immediate timeout, i.e., one that times out 
without waiting if and only if the response is not already buffered in the local machine. 

The defaultWaitTime equal to one minute is taken from the NS Internet Transport 
specification's value for maximum packet lifetime. The defaultRetransmissionlnterval is 
used to insure that requests will be transmitted at least two times before abandoning the 
effort. 

PacketExchange.maxBlockLength: readonly cardinal, 

The maximum length of the block (Environment.Block) that can be transmitted via 
PacketExchange is based on the maximum internet packet size , a value that is stated in the 
NS Internet Transport specification. Attempting to send requests or replies longer than 
PacketExchange. maxBlockLength will cause an error to be raised. 

6.2.2 Signals and errors 

PacketExchange. Error: ERROR [why: PacketExchange. ErrorReason]; 

PacketExchange. ErrorReason: TYPE = { 

blockTooBig, blockTooSmall, noDestinationSocket, noRouteToDestination, 
noReceiverAtDestination, insufficientResourcesAtDestination, rejectedByReceiver, 
hardwareProblem, aborted, timeout}; 

PacketExchange. Error may be raised by most of the request/reply procedures. The definitions 

The block the client attempted to transmit was too 
big. The size of the block must be in the range 

[0.. PacketExchange. maxBlockLength). 

The block specified by the client to receive a request 
or reply was smaller than the amount of data 
transmitted. 

This error code is obsolete and unimplemented. 

When attempting to transmit a request, it was found 
that the internet was partitioned in such a manner 
that the target network is not reachable, or the 
network field of the remote address is invalid. The 
remote host has not been contacted. 

A request was sent to a machine that does not 
currently have a replier listening on that socket. 


of ErrorReason are as follows: 
blockTooBig 

blockTooSmall 

noDestinationSocket 
noRouteToDesti nation 

noReceiverAtDestination 
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Communication with the remote machine has been 
achieved. 


insufficientResourcesAtDestination An error packet was received in response to a 

PacketExchange request. The indication is that 
either an intermediate internet router or the target 
machine does not currently have the resources to 
service the request. 

rejectedByReceiver The request was rejected by the replier for some 

undetermined reason. Communication with the 
remote machine has been achieved. 


hardwareProblem 


An undefined error packet was received in response 
to a request. 


aborted 


This error code is obsolete and unimplemented. 


timeout 


This error code is used for internal processing and 
should not be observed by PacketExchange clients. 


PacketExchange.Timeout: signal; 

The time interval set in one of the create routines (PacketExchange.CreateRequestor or 
CreateReplier) or PacketExchange. SetWaitTimes has expired and the operation has not 
completed. This signal may be RESUME’d in order to wait another timeout interval. 

6.2,3 Procedures 

PacketExchange.CreateRequestor: procedure [ 

waitTime: PacketExchange.WaitTime *— PacketExchange.defaultWaitTime, 
retransmissionlnterval: PacketExchange.WaitTime 
PacketExchange.defaultRetransmissionlnterval] 

RETURNS [PacketExchange. ExchangeHandle]; 

CreateRequestor creates a socket on a unique local address. The requestor's wait time and 
retransmission interval may be specified using the parameters waitTime and 
retransmissionlnterval. The successful return from CreateRequestor results in the client 
possessing a valid exchange handle that may then be used as an argument in a 
PacketExchange. SendRequest or Delete. CreateRequestor generates no transmissions to any 
host and will raise no signals. 

PacketExchange.CreateReplier: PROCEDURE [ 

local: System.NetworkAddress, requestCount: cardinal*- 1, 
waitTime: PacketExchange.WaitTime «- PacketExchange.defaultWaitTime, 
retransmissionlnterval: PacketExchange.WaitTime <- 
PacketExchange.defaultRetransmissionlnterval] 

RETURNS [PacketExchange. ExchangeHandle]; 

CreateReplier creates a PacketExchange replier at the well known address, local. Since it 
is expected that repliers are supplying a service to many clients, clients of CreateReplier 
may request more buffering via requestCount. requestCount represents the number of 
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requests that may be queued to the replier at any given time. This permits the replier 
process time to service a request and still not miss new requests that arrive while that 
processing is in progress. 

PacketExchange.Delete: PROCEDURE [h: PacketExchange.ExchdngeHandle]; 

When a requestor or a replier is no longer needed, it must be deleted. Once deleted, the 
exchange handle is no longer valid. 

Caution: If a client process is waiting inside the packet exchange implementation (either 
at WaitForRequest or SendRequest) and the requestor or replier is deleted, that process 
(or processes) will be aborted and the aborted signal will be permitted to propogate to the 
caller. This action is taken despite the popular notion that deleting an instance of a 
facility with client processes still active inside that facility is a client error. 

PacketExchange.RejectRequest: PROCEDURE [ 

h: PacketExchange.ExchangeHandle, rH: PacketExchange.RequestHandle]; 

If a replier client does not wish to respond to a request, the request may be rejected by 
calling PacketExchange.RejectRequest. This permits the implementation to delete the small 
state object represented by rH, the request handle. 

PacketExchange.SendReply: PROCEDURE [ 
h: PacketExchange.ExchangeHandle, 

rH: PacketExchange.RequestHandle, replyBIk: Environment. Block, 
replyType: PacketExchange.ExchangeClientType unspecified]; 

To respond to a request, the client calls PacketExchange.SendReply, specifying the exchange 
handle (h) used when he called PacketExchange.WaitForRequest and the request handle (rH) 
returned by that procedure. replyBIk describes the data that is to be sent in response. That 
block cannot be larger that PacketExchange.maxBlockLength. The reply packet will have an 
exchange identifier set to the value specified in replyType. This procedure may signal 
PacketExchange.Error. 

PacketExchange.SendRequeSt: PROCEDURE [ 

h: PacketExchange.ExchangeHandle, remote: System. NetworkAddress, 
requestBik, replyBIk: Environment.Block, 

requestType: PacketExchange. ExchangeClientType unspecified] 

returns [nBytes: cardinal, replyType: PacketExchange. ExchangeClientType]; 

A client that possesses a valid exchange handle (h) may send a request to a remote 
machine that implements a service in the form of a replier . The request must include an 
Environment.Block that represents the request (requestBik) and describes no more than 
PacketExchange.maxBlockLength bytes. The client must also specify an area for the reply to 
be stored, replyBIk. requestBik and replyBIk may describe the same area, and either or 
both may be Environment.nullBlock if the protocol being implemented permits it. The value 
of requestType will be copied into the exchange packet and may be used for filtering at the 
replier. 

SendRequest will return only after a valid response has been received. When it returns, 
replyBIk will contain nBytes of client data, and the reply received will be of type 
replyType. This procedure may signal PacketExchange. Error or PacketExchange.Timeout The 
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latter may be RESUME*d causing the request to reenter the timeout interval. It is important 
to note the difference between RESUME'ng and RETRY'ng. RESUME'ng will not assign a new 
exchange identifier permitting the replier to suppress any retransmissions as duplicates if 
appropriate. RETRY’ng will cause a new identifier to be assigned and the replier will not be 
able to detect it as a duplicate. 

Note: SendRequest may be aborted via Process.Abort. The ABORTED signal will not be 
caught by SendRequest. 

PacketExchange.SetWaitTimeS: PROCEDURE [ 

h: PacketExchange.ExchangeHandle, waitTime, retransmissionlnterval: 

Packet Exchange. Wa itTi me]; 

SetWaitTimes permits an exchange client to adjust the timeout values associated with a 
exchange handle. waitTime affects both PacketExchange.WaitForRequest and SendRequest 
while retransmissionlnterval affects only the latter. Refer to §6.2.1 for additional details 
about wait times. This procedure raises no signals. 

PacketExchange.WaitForRequest: PROCEDURE [ 

h: PacketExchange.ExchangeHandle, requestBlk: Environment.Block, 
requiredRequestType: PacketExchange.ExchangeClientType unspecified] 
returns [rH: PacketExchange.RequestHandle]; 

A client that has created a replier via PacketExchange.CreateReplier is expected then to wait 
for a request to arrive. That is done by calling WaitForRequest. It requires a 
PacketExchange.ExchangeHandle, and an Environment.Block (requestBlk) in which to receive 
the data of the request. The field requiredRequestType may be set to a unique 
PacketExchange.ExchangeClientType or allowed to default to unspecified indicating that the 
exchange client type of the request is not a significant part of the protocol. If 
requiredRequestType is not unspecified then only requests of type requiredRequestType 
will be accepted. 

PacketExchange.WaitForRequest will return only when a suitable request has arrived. When 
it does, the data structure pointed to by rH will contain additional information about the 
request. That information may be used by the client to determine if the request is a 
duplicate or to be ignored for any reason. Once the procedure returns with rH, rH must be 
accounted for in one of two manners. It must either be the object of a 
PacketExchange.SendReply (the norm), or it must be dispensed with via 
PacketExchange.RejectRequest. 

This procedure may signal PacketExchange. Error and Timeout. The latter signal may be 
RESUME'd. It would be quite usual to specify an infinite timeout on a replier, thus 
eliminating the need to service the PacketExchange.Timeout signal. 

Note: WaitForRequest may be aborted via Process.Abort. The ABORTED signal will not be 
caught by WaitForRequest. 

6.3 Network streams 

NetworkStream: definitions ...; 
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A Network stream is the principal means by which clients of Pilot communicate between 
machines. Network Stream provides access to the implementation of the Sequenced Packet 
Protocol — a level 2 Internet Transport Protocol which is defined in Xerox Internet 
Transport Protocols . It provides sequenced, duplicate-suppressed, error-free, flow- 
controlled communication over arbitrarily interconnected communication networks. 

The Network stream package is implemented by Communication, bed. 

As previously mentioned, NetworkStream is implemented by a sequenced packet transducer 
which utilizes sockets to communicate with machines on a communication network. All 
data transmission via a Network stream is invoked by means of Stream operations. Here, 
the most common model of communication using Network streams will be described. 
Subsequent sections provide a description of the actual NetworkStream primitives. 

A Network stream provides reliable communication between any two network addresses 
(System. NetworkAddresses). The stream (connection) can be set up between the two 
communicators in many ways - the most typical case involves a supplier of a service at 
one end, and a client of the service at the other. Creation of such a stream is inherently 
asymmetric. 

At one end is a server ~ that is, a process or subsystem offering some service. When a 
server is operational, one of its processes listens for connection requests on its network 
address (which has previously been made known to potential clients through some binding 
mechanism) and creates a new Network stream for each separate request it receives. The 
handle for the new stream is typically passed to a subsidiary process or subsystem (called 
an agent) which gives its full attention to performing the service for that particular client. 

At the other end is the client of the service. This process or subsystem requests service by 
actively creating a Network stream, specifying the network address of the server as a 
parameter. The effect is to create a connection between the client and its server agent. 
These two then communicate by means of the new Network stream set up between them 
for the duration of the service. 

It is not necessary that the client and server be on different machines. If they are on the 
same machine, Pilot will optimize the transmission of data between them and will avoid 
the use of physical network resources. Thus, a client does not need to know where a server 
is located. This scheme permits configuration flexibility — permitting services that reside 
on one machine to be split across a number of machines connected together by a network, 
or vice versa. 

The manner in which a client finds out the network address of a server, or the manner in 
which a server makes its network address known to potential clients is outside the scope of 
Pilot. 

6.3.1 Types and constants 

NetworkStream.WaitTime: TYPE = LONG CARDINAL; 

WaitTime is used in reference to establishing intervals for timeouts. The value associated 
with the type is always in milliseconds. 
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Note: If a wait time interval is asigned a value of zero, subsequent operations will timeout 
immediately if data is not present when a data request is made. 

Caution: The wait time is converted to an internal format to be used by the 
implementation. If that conversion results in an overflow, subsequent timed operations 
will never timeout. Clients should use caution when attempting to set timeouts of more 
than approximately 40 minutes. 

NetworkStream.defaultWaitTime: WaitTime * 60000; 

The default wait time of 60 seconds is a value taken from the maximum internet packet 
lifetime. 

Networkstream.infiniteWaitTime: readonly Networkstream. WaitTime; 

The infinite wait time is equivalent to asserting that the operation will never time out, or 
there is no interest in processing timeouts. It is assumed that any process that uses this 
value will also be capable of aborting the affected process at some time. 

Networkstream. ClassOfService: type ■ {bulk, transactional}; 

The class of service parameter permits the client to convey some hint as to the use of the 
transport being created. If a client hints the transport is bulk, the assertion is that it will 
be used for a high performance application, such as file transfer or the like. If the client 
hints transactional it is assumed that the transport will be used for alternating traffic, an 
example of which is remote procedure calls as implemented by Courier. 

Networkstream. uniqueNetworkAddr: readonly System. NetworkAddress; 

The value uniqueNetworkAddr may be used as a local address specification to indicate to 
the underlying code that any legal locally generated network address is applicable. This is 
equivalent to the client calling NetworkStream.AssignNetworkAddress and using the result 
as the parameter value. 

NetworkStream.ConnectionID: TYPE[1]; 

Networkstream.uniqueConnID: readonly NetworkStream.ConnectionID; 

Networkstream.unknownConnID: readonly NetworkStream.ConnectionID; 

A connection identifier is a 16-bit value that is unique within a particular machine. It may 
not be unique across system restarts. It is used in conjunction with the network address to 
fully define a Sequence Packet Protocol connection. The value 
Networkstream.uniqueConnID may be used by clients of NetworkStream.CreateTransducer to 
indicate that they want the implementation to generate a unique ConnectionID. This is 
equivalent to the client calling Networkstream.GetUniqueConnectionID directly and using 
the result for the same parameter. Networkstream.unknownConnID may be assigned to the 
remoteConnID parameter in a NetworkStream.CreateTransducer call. It indicates that the 
connection identifier will be supplied by the remote machine. 


Networkstream.ListenerHandle: type [2]; 




6 


Communication 


The ListenerHaridle is the result of a NetworkStream.CreateListener and is required as a 
parameter on all other listener operations. 

6*3.2 Creating Network streams 

Clients are provided access to a Network stream via the Stream. Handle and the 
Stream. Object that it references. Network streams are variants of generic Pilot streams. 
For the general definition of Pilot streams, see Chapter 3. 

Network streams are usually created in one of two ways depending on whether the stream 
is supporting a client that is consuming a service or providing a service. The consumer will 
use NetworkStream.Create while the server uses the listener mechanism. Both processes are 
clients ofNetworkStream.CreateTransducer. CreateTransducer may also be called directly by 
clients, provided they are familiar with the options it permits. 

Networkstream.CreateTransducer: procedure [ 
local, remote: System.NetworkAddress, 

COnnectData: Environment.Block Environment.nullBlock, 
localConnID, remoteConnID: Networkstream.ConnectionID, 
activelyEstablish: boolean, 

timeout: NetworkStream.WaitTime NetworkStrearn.defaultWaitTime, 
classOfService: Networkstream.ClassOfService bulk] 

RETURNS [Stream. Handle]; 

Networkstream.CreateTransducer will not return to the caller with the stream. Handle until 
the connection is fully established. When established, the stream is ready to perform 
stream operations with the cooperating partner of the connection as specified in remote. 
The value local is usually specified as NetworkStream.uniqueNetworkAddr. This value is 
recognized by the create process and will cause a unique address to be generated. That 
address is generated by calling NetworkSteam.AssignNetworkAddress. (The client is 
welcome to call the routine directly and use its results for the value of local.) It is not 
recommended that local consume a well known socket. The remote address must be fully 
specified, including the socket. The socket field of remote may be a well known socket. If 
so, the connection actually established will not consume that socket, but generate a 
unique network address in its place. 

localConnID is usually defaulted to NetworkStream.uniqueConnID. Alternatively, the client 
may use the results of NetworkStream.GetUniqueConnectionID for the value of localConnID. 
Usually, the value of remoteConnID is set to NetworkStream.unknownConnID. This asserts 
that the value of the remote's connection identifier will be generated be the remote 
machine and its value conveyed during the connection rendezvous. 

The boolean activelyEstablish is used to establish the solicitor/listener relationship 
normally required to arbitrate a connection. If activelyEstablish is TRUE, the create process 
will transmit connection requests to the remote. If it is false, it will merely listen for the 
connection requests. In some cases, both parties know the entire set of connection 
parameters, including the connection identifiers. This implies some previous binding 
arbitration has occurred. It is possible, under those conditions, to create transducers on 
both the local and remote machines that are fully established, without transmitting any 
information at all. 
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When creating a transducer, timeout is used for two different purposes. If 
activelyEstablish is TRUE, it will be used as the time allowed for the remote to respond to the 
connection establishment requests. It will also be used as the value of timeout for stream 
get operations, i.e., the interval permitted to expire during data input operations before 
the stream implementation signals Stream.TirneOut. 

The classOfService parameter affords the client the opportunity to hint the type of 
application the stream is to support. Both parties of the connection should select the same 
class, transactional will be assumed if there is disagreement. 

The Stream. Handle returned is a variant of a generic Pilot byte stream handle. The 
positioning operations, getPosition and setPosition, are unimplemented and will result in 

stream. InvalidOperation. 

CreateTransducer may generate the error NetworkStream.ConnectionFailed. A process 
blocked in CreateTransducer may also be aborted (Process.Abort). CreateTransducer will 
not catch the aborted signal. 

6.3.2.1 Creating client streams 

NetworkStream. Create: PROCEDURE [ 
remote: System. NetworkAddress, 

COnnectData: Environment.Block Environment.nullBlock, 
timeout: NetworkStream.WaitTime *-NetworkStrearn.defaultWaitTime, 
classOfService: NetworkStream.ClassOfService <- bulk] 

RETURNS [stream. Handle]; 

Create is the most common method that a client stream client uses to solicit the creation of 
a transport to a server client. This procedure is a client of NetworkStream.CreateTransducer. 
Create assigned a value of NetworkStream.uniqueNetworkAddress to local, 
NetworkStream.uniqueConnectionID to localConnID and asserts activelyEstablish to be true 
causing the process to transmit the needed request packets to solicit the connection. 

6.3.2.2 Creating server streams 

Networkstream.CreateUstener: procedure [addr: System.NetworkAddress] 

RETURNS [NetworkStream. ListenerHandle]; 

Creating a listener creates the state object (represented by the ListenerHandle). The state 
object includes a socket at addr. CreateListener does not cause any data to be transmitted. 
It does provide the necessary buffering and queuing to receive data. A listener will exist as 
such until it is deleted via NetworkStream. DeleteListener. CreateListener generates no 
signals. 

NetworkStream. Listen: PROCEDURE! 

listenerH: NetworkStream. ListenerHandle, 

COnnectData: Environment.Block Environment.nullBlock, 

listenTimeout: Networkstream.WaitTime^-NetworkStream.infiniteWaitTirne] 
RETURNS[remote: System. NetworkAddress, bytes: cardinal]; 
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Once a listener is created, the client must provide the process to actually listen. This is 
done by calling NetworkStream. Listen. When an acceptable connection request packet 
arrives at the address specified in CreateListener, Listen will return with the network 
address of the requestor (remote) and the number of bytes received (bytes) in the 
rendezvous. The client then has the opportunity to reject or honor the connection request. 
A connection request is rejected either by calling NetworkStream. Listen again or by deleting 
the listener. Both will cause an error packet to be transmitted to the requestor. 

If no suitable packet arrives at the socket in listenTimeout milliseconds, listen will raise 
the signal NetworkStream. ListenTimeout. This signal may be resumed. The default value of 
infiniteWaitTime implies that the listener should never timeout, which is an acceptable 
(and normal) practice. 

NetworkStream.ApproveConnection: procedure [ 
listenerH: NetworkStream.ListenerHandle, 

streamTimeout: NetworkStrearn.WaitTime ^-NetworkStream.infiniteWaitTime, 
classOfService: NetworkStream.ClassOfService «- bulk] 

RETURNS [sH: Stream. Handle]; 

When NetworkStream.Listen returns and the client wishes to honor the connection request, 
he calls NetworkStream.ApproveConnection. ApproveConnection is a client of 
NetworkStream.CreateTransducer. The local address and connection identifier are defaulted 
to NetworkStream.uniqueNetworkAddr and NetworkSteam.uniqueConnID respectively. The 
values for remote address and connection identifier are taken from the appropriate fields 
of the packet requesting the connection. The client is given the opportunity to provide a 
hint about the expected application of the stream by assigning an appropriate value to 
classOfService. This hint should agree with the hint provided by the remote requestor. 

In spite of the evidence that a communication path exists between the local machine and 
the remote requestor, this procedure may still signal NetworkStream.ConnectionFailed. 

NetworkStream. DeleteListener: procedure [listenerH: NetworkStream. ListenerHandle]; 

Should the client desire to no longer listen at the socket specified in CreateListener, the 
listener should be deleted. It is advised that this be done at a time when no process is 
actively listening. The Listen process is abortable (Process. Abort). The procedure 
DeleteListener may signal NetworkStream. LlstenError if listenerH does not represent a valid 
ListenerHandle. 

Caution: If DeleteListener notices a process blocked in Listen, it will abort that process 
and the signal ABORTED will be propogated to the Listen client. This action is taken despite 
the popular notion that deleting an instance of a facility with active processes inside that 
facility is a client error. 

6*3.3 Signals and errors 

NetworkStream.ConnectionSuspended: error [why: NetworkStream. SuspendReason]; 
NetworkStream.SuspendReason: type ■ { 

notSuspended, transmissionTimeout, noRouteToDestination, 
remoteServiceDisappeared}; 
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Clients of Pilot streams that are implemented by Network streams are responsible for 
catching not only all Stream signals, but also a Network streams unique signal. That 
signal is ConnectionSuspended, a name the implies the stream has been established but 
now is failing. The signal carries with it a reason for the suspension, and the table 
following describes the reasons. 

notSuspended The connection is not suspended. This state should never 

be observed by a client. It is included to simplify internal 
processing. 

transmissionTimeout A connection that was previously communicating has not 

seen a response from the remote machine for an extended 
period of time. The internal processing of SPP retransmits 
packets at computed intervals until they are acknowleged. 
If a packet is retransmitted more than 30 times without 
acknowlegement, the connection is abandoned. The 
interval between retransmissions is computed based upon 
previous response rates and is initially (before statistics 
can be gathered) based on the number of internet routers 
that the packet must pass through to reach the remote 
machine. In the absence of retransmissions and in 
conjunction with them, idle line probes are also 
transmitted at computed intervals to the remote host. The 
number of probes that will be transmitted without 
acknowlegement is fixed, and the interval between probe 
transmissions is computed based simply on the number of 
internet routers that the packet must pass through to 
reach the remote machine. 

noRouteToDesti nation A previously functional connection has discovered that the 

internet has become partitioned in some manner that the 
remote host is no longer accessable, either because it must 
pass through too may internet routers or a path has totally 
disappeared. 

remoteServiceDisappeared A previously functional connection has been notified that 

the remote address no longer exists. In other words, the 
socket on which the connection was based has been 
deleted. 

Networkstream.ConnectionFailed: signal [why: Networkstream.FailureReason]; 
Networkstream.FailureReason: type = { 

timeout, noRouteToDesti nation, noServiceAtDesti nation, remoteReject, 
tooManyConnections, noAnswerOrBusy, noTranslationForDestination, circuitlnUse, 
circuitNotReady, noDialingHardware, dialerHardwareProblem}; 

Networkstream.ConnectionFailed is applicable only to clients who are attempting to 
establish a SPP connection. This includes clients of NetworkStream.CreateTransducer, 
Create and ApproveConnection. The implication is that the connection never was 
established; it does not always conclude that the remote machine was not contacted. 
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timeout 


noRouteToOestination 


noServiceAtDestination 


remoteReject 


tooManyConnections 


noAnswerOrBusy 


noTranslationForDestination 


circuitlnUse 


circuitNotReady 


noDialingHardware 


The time stated in the parameter timeout of 
NetworkStream.CreateTransducer has expired and the 
packets requesting connection establishment have not 
been acknowleged. This and only this value of why may be 
resumed. 

Attempts to find a route to the remote network failed. 
Either the network is temporarily partitioned in such a 
manner that the network is unreachable or the network 
number in the remote address is invalid. In any case, the 
remote host has not been contacted. 

There is no listener at the address specified in the remote 
address. The machine did respond indicating that the 
internet and the machine are both responsive. 

The process implementing the service at the remote 
address rejected the request for connection (see §6.3„2.2). 
Since the remote host sent the reject, it is obvious that the 
internet and the remote host are both responsive. 

The number of simultaneous connections permitted on the 
local machine would have been exceeded by creating a new 
stream. In cases where activelyEstablish is true (e.g., 
MetworkStream. Create), no communication with a remote 
machine has been attempted. 

This error is applicable only to circuit oriented 

connections. When the phone was dialed, it was either not 
answered or was busy. The remote machine has not been 
contacted. 

This error is applicable only to circuit oriented 

connections. There is no phone number currently 
registered for access to the network specified. The remote 
machine has not been accessed. 

This error is applicable only to circuit oriented 

connections. The circuit that must be used to access the 
remote machine is currently in use. The remote machine 
has not been contacted. 

This error is applicable only to circuit oriented 

connections. The circuit that must be used to access the 
remote machine was not ready. Possibly the modems need 
to be made ready or the phone needs to be manually dialed. 
The remote machine has not been contacted. 

An attempt to access a remote network that would require 
a circuit oriented device, but the proper hardware does not 
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exist to make such a connection. The remote machine has 
not been contacted. 

dialerHardwareProblem An attempt to access a remote network that would require 

a circuit oriented device, but the hardware needed to make 
such a connection appears to be inoperable. The remote 
machine has not been contacted. 

Networkstream.ListenError: error [reason: NetworkStream.ListenErrorReason]; 

Networkstream.ListenErrorReason: type = { 

illegalAddress, illegalHandle, illegalState, blockTooShort}; 

Networkstream.ListenError is applicable only to clients of the listening procedures. The 
definition of the error reason is as follows: 

illegalAddress The local address specified in NetworkStream.CreateListener 

is illegal. This is due to the fact that addr already exists on 
the local machine or the socket field of addr has a value of 
zero. 

The handle specified in one of the listener procedures is not 
valid. Either the handle has been deleted 
(NetworkStream. DeleteListener) or was never created. 

The state of the listener handle specified to one of the 
listener procedures (NetworkStream.ApproveConnection or 
Listen) was in an illegal state for that operation. In the 
case of NetworkStream.ApproveConnection, the state 
indicated that no request for connection had been received. 
In the case of NetworkStream.Listen, a process was already 
found to be listening, implying that two or processes are 
sharing the listener handle. 

The Environment. Block provided to collect the connection 
data in NetworkStream. Listen was not large enough to hold 
the data supplied by the requestor of the connection. (Note: 
The ability to pass rendezvous information is not currently 
implemented. Consequently, this status should never be 
observed.) 

NetworkStream. ListenTimeout: signal; 

NetworkStream.ListenTimeout will be raised if no acceptable packet arrives at the listener 
within the specified time interval. That interval is client specified in 
NetworkStream.CreateListener as listenTimeout. This signal may be resumeM, causing the 
interval to be reentered. It is a common practice to use NetworkStream.infiniteWaitTime as a 
value for listenTimeout when creating listeners to eliminate the need to process the 
ListenTimeout signal. 

6.3.4 Utilities 


illegalHandle 


illegalState 


blockTooShort 
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The following utility functions are avaible to NetworkStream clients. In general they 
provide functionality unique to Network streams. 

6.3.4.1 Assigning unique address components 

Networkstream.AssignNetworkAddress: procedure returns [System. NetworkAddress]; 

AssignNetworkAddress returns to the caller a network address that is unique for the 
current system restart. It is constructed from the local machine’s network number for the 
default communication device, the local machine's processor identification number, and a 
unique socket number that is not a well known. The result is applicable to any argument 
that might use a unique local address. 

NetworkStream.GetUniqueConnectionID: procedure 
RETURNS [iD: NetworkStream.ConnectionID]; 

GetUniqueConnectionID will return to the caller a connection identifier that is unique 
within the current system load. It may be used any place a 
NetworkStream. uniqueConnectionID would be applicable (NetworkStream.CreateTransducer). 


6«3„4.2 Discovering addresses of established streams 

NetworkStream. FindAddresses: procedure [sH: stream.Handle] 
returns [local, remote: System. NetworkAddress]; 

A client may find the local and remote network addresses of an existing stream by calling 

FindAddresses. 

B.3.4.3 Controlling timeouts 

NetworkStrearn.SetWaitTime: PROCEDURE [sH: Stream.Handle,time: NetworkStrearn.WaitTime]; 

This procedure may be used to adjust the stream timeout of an established network 
stream. 

Note: Since the generic Pilot stream also provides the same capability, it is suggested that 
use of this procedure be phased out in preference to the standard operation. This operation 
will be removed in the next release of Pilot. 


6o3.4.4 Closing streams 

An implementation of a close protocol is provided by Network streams. This method of 
terminating dialog on a stream is suggested in the NS Internet Protocol Specification. 
Use of these routines (or any like them) is considered optional. 

NetworkStream. CloseStafus: type ■ {good, noReply, incomplete}; 

NetworkStream. closeSST: stream. SubSequenceType = 254; 

Networkstream.closeReplySST: stream.SubSequenceType s 255; 
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NetworkStream. Close: PROCEDURE [sH: Stream. Handle] 

RETURNS [NetworkStream. ClOSeStatUS]; * 

NetworkStream. CIOSeReply: PROCEDURE [$H: Stream. Handle] 

RETURNS [NetworkStream. ClOSeStatUS]; 

To initiate a close sequence, a client may call NetworkStream.Close. That procedure will 
transmit an empty packet with a Stream.SubSequenceType of NetworkStream.closeSST. The 
side effect of this is that all buffered data will be transmitted before the empty packet. 
After the closeSST has been transmitted, the procedure will attempt to receive a 
NetworkStream.closeReplySST. All data not of subsequence type closeReplySST will be 
ignored. When a NetworkStream.closeReplySST is received, the procedure will transmit 
NetworkStream.closeReplySST and return, without waiting. NetworkStream.Close raises no 
signals. 

If a client protocol uses the close procedure and receives a NetworkStream.closeSST, it should 
respond by calling NetworkStream.CloseReply. This procedure will transmit a 
NetworkStream.closeReplySST, the side effect of which will be to force transmission of all 
currently buffered data. After sending the closeReplySST, the procedure will attempt to 
receive a packet with subsequence type of closeReplySST. NetworkStream.CloseReply raises 
no signals. 


The NetworkStream. CloseStatus has the following definitions: 


good 


noReply 


incomplete 


The close protocol terminated cleanly. All data the was buffered by the 
stream implementation prior to initiating the close was transmitted 
and acknowleged at least to the level of the Network stream client. 

There was no response to the NetworkStream. closeSST. All data buffered 
in the local stream implementation has been transmitted, but may not 
have been acknowleged. 

The local machine transmitted a NetworkStream.closeReplySST in. 
response to a NetworkStream.closeSST and received no response. All data 
buffered in the local stream implementation has been transmitted and 
acknowleged. The closeReplySST is expected, but not required. 


6.3.5 Attributes of Network streams 

Network streams are byte streams built on top of the Sequenced Packet Protocol . Due to 
the distributed nature of the streams clients may find some behavior unique. This section 
will attempt to point out the unique areas of these streams with the intent of assisting in 
design and debugging applications using Network streams. 

All output operations (putByte, putWord, put, setSST, sendAttention, sendNow) buffer 
the data internally, transmitting those buffers only when they are either full or the 
semantics of an operation indicate they must be transmitted. When the buffers are 
actually transmitted it is possible that the client process will be blocked indefinitely if the 
remote partner in the connection is not consuming data. This is known as the waiting for 
allocation state. All output operations may signal NetworkStream.ConnectionSuspended. 
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All input operations (getByte, getWord, get) may signal any of the defined Stream errors, 
except Stream.EndOfStream. The end of stream concept is not implemented by Network 
streams. All input operations may also signal NetworkStream.ConnectionSuspended. 
Physical packet boundaries will not be visable to the byte stream client, but they may be 
inferred through the input operation status or signals. Any operation that signals or 
returns a completion status other than normal is at a packet boundary. On a normal 
return the stream may or may not be at a packet boundary. 

Any Network stream operation may be aborted (Process.Abort). The aborted signal will be 
permitted to propogate to the stream client. 

6.3.5.1 Elements of Network stream objects 

Elements of a Network Stream.Object are:. 

inputOptions The defaultlnputOptions defined by the Stream interface are almost 
always inappropriate for Network streams. In particular, 
terminateOnEndRecord should be true. This is due to the fact that 
Network streams do not implement the end of stream concept, but do 
have the concept of a message or logical record . If 

terminateOnEndRecord is false, input operations will not terminate at 
the end of the logical record and the return status endRecord will never 
be observed. If a get is not permitted to terminate with an ebdRecord 
status, it will invariably find itself waiting to complete a transfer when 
it should be responding to the Information it has in hand. 

getByte GetByte returns the byte of data from the byte stream. It asserts the 

input options as [false, false, false, true, true, true, true, false], making 
the signals Stream. SSTChange, Stream.Attention or Stream.TimeOut 
possible. 

putByte PutByte appends one byte of client data to the byte stream. Should that 

addition cause the internal buffer to be filled, it will be transmitted over 
the established connection. 

getWord GetWord returns the word of data from the byte stream. It asserts the 

input options as [false, false, false, true, true, true, true, false], making 
the signals Stream.SSTChange, Stream.Attention or Stream.TimeOut 
possible. GetWord operations that signal SSTChange or Attention are 
ambiguous if the signal is raised after processing half (or one byte) of 
the request. Such ambiguity is a client error. The sender and receiver 
should use the same type of alignment characteristics. 

putWord PutWord appends one word of client data to the byte stream. Should 

that addition cause the internal buffer to be filled, it will be transmitted 
over the established connection. 

get Get retrieves the number of bytes specified in block (Environfhent.Block). 

If the number of bytes requested is actually transferred, the status 
returned by get will always be normal unless the inputOptions have 
been set to terminateOnEndOfRecord and the end of the logical record 
is detected. Conversely, a completion code of anything other than 
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normal or endRecord implies that the transfer operation was not 
satisfied. The input options are settable by the client, so the various 
stream signals are possible depending on the options. 

If signalLongBlock or signalShortBlock is true, packet boundary 
semantics will be applied to the byte stream and the client will be 
notified by the appropriate signal Stream. LongBlock or Stream. ShortBlock. 
These two input options should be used only by clients that wish to 
directly control buffering, and those clients would be well advised to use 
something other than Network streams in their application, 

put Put appends the specified block (Environment.Block) to the byte stream. 

That addition may cause any (bounded) number of internal buffers to be 
transmitted. The parameter endRecord may be set to true causing the 
any currently buffered data to be transmitted and define the end of a 
logical record. A put specifying no bytes and with endRecord set to true 
is equivalent to a sendNow with endRecord set to true. The endRecord 
status is preserved by the Network stream and detectable by the 
receiving client. 

setSST SetSST will cause a buffer to be transmitted with the current sst if and 

only if the new sst is of a different value. If there was no data buffered, 
an empty buffer will be transmitted carrying only the changed sst state. 
And lastly, the new sst will be recorded and declared to be the current 
sst. When a stream is created, it is assigned a default sst of value 0. 

sendAttention SendAttention causes an attention byte to be appended to the byte 
stream. The Network stream implementation also performs some 
heroics in its attempts to deliver attentions. This amounts to expediting 
the delivery, circumventing, if necessary, SPP allocation window 
constraints. SendAttention assumes the receiver is taking equally 
heroic action. Due to the additional overhead in such operations, it is 
advised that attentions be used judiciously. 

waitAttention WaitAttention allows the client process to wait for an out-of-band 
attention notification. If a sending client is transmitting attentions, it is 
the responsibility of the receiving client to process both the in-band and 
out-of-band attentions. Failure to do so is a client error and will cause 
the stream to fail. Only a small number of out-of-band attentions will be 
maintained (less than 10). When that number is reached, the connection 
will no longer be able to receive data. 

delete Delete causes the current processes and buffering used by the stream 

implementation to be destroyed. No attempt to clean up the stream is 
made. The remote partner of the connection is not notified that the local 
has been deleted. It is a client responsibility to insure that the 
application data has been satisfactorily delivered before deleting the 
connection. 

getPosition GetPosition is not implemented by Network streams. 
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setPosition SetPosition is not implemented by Network streams. 

sendNow SendNow forces transmission of a buffer. That buffer may contain 

internally buffered data, or it may be an empty buffer. SendNow with 
endRecord set to true defines the end of a logical record. The logical 
record boundary status is preserved by Network streams during 
transmission and detectable by receiving clients. 

clientData This field is not used by Network streams. 

getSST GetSST will return to the caller the current output SST, i.e., the SST 

that can be set by the client via setSST, This procedure raises no signals. 


6.5.5.2 Input options 

terminateOnEndRecord If terminateOnEndRecord is false, the stream implementation 

will ignore logical record boundaries in incoming packets, and 
continue to process incoming packets until the get request is 
satisfied. If it is TRUE, it will assume an exceptional condition at 
the end of a packet that carries a logical record boundary status, 
terminate the transfer, and return with an endRecord 
completion code. 

signalEndOfStream Network streams do not implement this concept. 

6.3.5.3 Completion codes 

These codes are returned from the get procedure. 

normal A normal return is one that satisfies the transfer request, i.e., the 

number of bytes requested. 

endRecord An endRecord status indicates that in an attempt to satisfy the input 

request, a buffer that carries a end of logical record status was 
consumed and that the input options indicated that the request should 
terminateOnEndRecord. The input request may not be complete. 

sstChange This status indicates that the data stream type of the data stream has 

changed and that the next byte of data in the byte stream will be of type 
sst. The get procedure’s transfer is not complete. 

endOfStream The endOfStream concept is not implemented by Network streams. 

attention This status indicates that the next byte of the byte stream is an in-band 

attention byte. The in-band attention marks the point in the byte stream 
where the attention was transmitted, even though the out of band 
notification may have arrived at a different time. The get procedure’s 
transfer is not complete. 
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6.4 Routing 

Router: definitions ...; 

All routers transmit packets to an immediate host that is, or is closer to, the final 
destination host. Internetwork routers are responsible for keeping other internetwork 
routers and simple routers informed of as much of the topology as they require, and for the 
actual forwarding of packets from one net to another. They always know the topology of 
the entire internet. Simple routers are mostly ignorant of the network topology, and learn 
only enough about it to send packets sourced in the local machine toward their destination 
via the optimal route. Each instance of Pilot has a simple router to help direct packets to 
their proper destination. Router offers operations for using Pilot as a simple router, and for 
discovering information about the topology of the internetwork. 

Distances between networks are measured in the number of internetwork routers a packet 
must be routed through from source to destination. The unit of measurement used is a 
hop . The delay to a network is the number of hops from the source host to the destination 
host. The local network is always considered to be zero hops away; a network available 
through a single internetwork router is one hop away. 

The simple routers keep a routing table by which packet forwarding decisions are made. 
A routing table entry contains a destination network number, the internetwork router 
address to which packets bound for the destination network should be forwarded, and the 
delay to the network in hops. The routing table contains entries only for those destination 
networks that have been accessed (i.e., had traffic transmitted to them) within the last 
ninety seconds. The table entries are created when a client tries to send a packet to a 
network unknown to Pilot, causing a routing table cache fault. The fault causes at least 
one routing request to be made of a local internetwork router. The local routing table for a 
simple router grows only when routing table faults occur. Thus, it is not a complete 
picture of the networks that are reachable. 

The routing table for simple router is maintained by aging entries to which no traffic has 
been generated, and discarding the old entries. 

Router is implemented by the configuration Communication. bed. 

6.4.1 Types and constants 

Router.endEnumeration: readonly System.NetworkNumber; 

Returned by the EnumerateRoutingTable stateless enumerator, endEnumeration 
indicates the end of the list of entries in the current routing table has been reached. 

Router.infinity: cardinal ■ 16; 

infinity is the number of hops that defines an unreachable network. Any network that is 
infinity or more hops away from the local net is unreachable. 

Router.PhysicalMedium: type = {ethernet, ethernetOne, phonenet, clusternet}; 

PhysicalMedium defines the various types of networks on the device chain. 
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ethernet ethernet is a 10 M-bit ethernet, as defined by The Ethernet, Version 

1.0, September 30,1980. 

ethernetOne Also referred to as the experimental ethernet, ethernetOne is a 3 M-bit 
ethernet. 

phonenet Based on the create procedure in RS232C, phonenet is a phone line 

network. 

clusternet clusternet is a clusternet network, a group of one or more RS232C 

ports that is used for remote workstations. 

Router.RoutersFunction: type a {vanillaRouting, interNetworkRouting}; 

The type of routing function the current router has is defined by RoutersFunction. 

vanillaRouting The function for all simple routers is vanillaRouting. These 

routers are capable only of requesting routing information, 
receiving the responses from the internetwork routers and 
maintaininga table. 

interNetworkRouting The function for internetwork routers is 

interNetworkRouting. These are the routing information 
suppliers that know about the network topology. They respond 
to routing requests and periodically send out gratuitous 
routing information updates. 

Pilot directly supports only vanillaRouting. 

Router.startEnumeration: readonly System. NetworkNumber; 

Used with the EnumerateRoutingTable stateless enumerator, startEnumeration is passed 
to start the enumeration of the entries in the current routing table. 

6.4.2 Signals and errors 

Router.NetworkNonExistent: error; 

Raised by GetNetworkID and SetNetworkID, this error indicates the device specified in 
the call does not exist. 

Router.NoTableEntryForNet: error; 

Raised only by GetDelayToNet, this error indicates the network specified by the client 
could not be found in the routing table and the information could not be obtained from an 
internetwork router. 

6.4.3 Procedures 

Router. AssignAddress: procedure returns [System. NetworkAddress]; 

This procedure returns a network address with the primary network number ( i.e the first 
device on the device chain), the local machine’s ID and a unique socket number. It is 
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typically used by clients who need to generate a unique address. Note: this address is not 
unique across system restarts. 

Router.AssignDestinationRelativeAddress: procedure [System. NetworkNumber] 
returns [System. NetworkAddress]; 

Clients who wish to obtain their address with a unique socket number and who know what 
destination network they will be communicating with should call 
AssignDestinationRelativeAddress. The network number passed is the destination 
network number. Instead of setting the network field of the returned value to the primary 
network number, the procedure will set it to the number of the local network on the best 
known route to the destination net. The host field will be set to the processor ID of the 
local machine and socket field to a unique socket number. 

Router.EnumerateRoutingTable: procedure! 
previous: System.NetworkNumber, delay: cardinal] 
returns [net: System.NetworkNumber]; 

A stateless enumerator, EnumerateRoutingTable is used to dump that portion of the 
current local routing table which represents routes within a certain delay of the local 

The number of hops to the remote network the client is interested in is 
specified by delay. 

previous is the network number obtained from the last call. If this is the 
first call to the procedure, previous should be set to startEnumeration. 

EnumerateRoutingTable will return the net and delay of the first net following previous 
that has a delay equal to delay. Pilot's simple router holds only entries for those routes 
recently accessed (i.e., have had traffic transmitted to them within the last 90 seconds) or 
those that have been obtained by an explicit routing information request via 
FiilRoutingTable or GetDelayToNet. In general, a machine can be connected to more than 
one local network by having more than one ethernet controller. In this case, the machine 
also has more than one network address. To determine the list of local networks, 
EnumerateRoutingTable can be used with maxDelay set to 0. The networks are 
enumerated in ascending order of network number. 

Router.FillRoutingTable: procedure [maxDelay: cardinal *-Router.infinity]; 

FiilRoutingTable solicits information on all networks within the specified number of hops 
from the local net. 

maxDelay maxDelay is the maximum delay in hops of the networks that the client 
wishes to collect information about. The default value is infinity, filling the 
table with information about every known reachable network. 

Routing information requests are broadcast on the local network. All subsequent 
responses from the internetwork routers, whether associated with the request or 
gratutious, will cause information about networks maxDelay or less away to be saved in 
the local routing table. That information will be continuously updated if and when new 
information is received. 


network. 

delay 

previous 
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FillRoutingTable followed by EnumerateRoutingTable can be used to determine the 
networks within the desired number of hops from the local net. The filling will continue 
until all clients who have called FillRoutingTable call it again with a maxDelay of zero, 
indicating they are no longer interested in saving incoming entries. There mast be a call 
with a maxDelay of zero for every call with a non-zero delay in order to properly maintain 
the table. If multiple clients have called this procedure, the greatest maxDelay specified 
will be used in determining which entries to save in the table. 

Router.FindDestinationRelativeNetID: PROCEDURE[System. NetworkNumber] 
returns [System. NetworkNumber]; 

When passed the number of a destination net, FindDestinationRelativeNetID will return 
the number of the local network on the best known route to the destination network. It is 
useful for setting an unknown source network number when the destination network is 
known. 

Router.FindMyHostID: procedure returns [System. HostNumber]; 

This procedure returns the processor ID of the local machine. 

Router.GetDelayToNet: procedure [net: System. NetworkNumber] returns [delay: cardinal]; 

Clients who wish to find the current delay to a specific net may call GetDelayToNet 

net The number of the network that the client is interested in is specified by net. 

delay The number of hops from the local net to net is specified by delay. 

If the net is not found in the current routing table, Pilot requests routing information from 
local internetwork routers . If net is unknown to the local machine and cannot be obtained 
from the internetwork router, Router.NoTableEntryForNet is raised. 

GetDelayToNet is useful for determining timeouts and retransmission intervals for 
clients, restrict broadcasts, or for determining the network topology close to the system 
element. It might also be useful in choosing between two servers offering the same service, 
based upon the delay to each element. 

Router.GetNetworkID: PROCEDURE[physicalOrder: cardinal, medium: PhysicalMedium] 
returns [System. NetworkNumber]; 

The network number of any network directly attached to the local machine can be 
discovered by calling GetNetworkID 

physicalOrder The is the index of the network driver on the device chain is the 

physicalOrder. (the primary network always has a physical order of 
1 ) 

medium The type of network involved is medium. 

This procedure will raise the error NetworkNonExistent if there is no such device. 
Router.GetRouterFunction: procedure returns [RoutersFunction]; 
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Clients wishing to discover the function of the current router registered with Pilot may 
call GetRouterFunction. The function of the router supplied by Pilot is always 
vanillaRouting, the simple routing information requestor. Special facilities may be used 
to install an internetwork router on a machine. 

Router.SetNetworkID: procedure! 
physicalOrder: cardinal, medium: PhysicalMedium, 
newNetiD: System. NetworkNumber] 
returns [oldNetiD: System. NetworkNumber]; 

Special clients can change their network number without rebooting by calling 

SetNetworkID. 

physicalOrder 
medium 
newNetiD 


oldNetiD 


The order of the network on the device chain is the physicalOrder. 
medium is the type of network. 

The new network number assigned to the specified device is 

newNetiD. 

The network number previously associated with the device is 

oldNetiD 


A call to this procedure may raise the error Router.NetworkNonExistent if there is no 
such device. 

Caution: This procedure should only be used by sophisticated clients who are 

knowledgable about the network and network numbers ( i.e ., Internetwork router 
implementations). 


6.5 RS232C communication facilities 

Pilot supports channel-level access to multiple full-duplex RS232C ports providing all of 
the standard channel procedures listed in §5.1, as well as several specific to RS232C 
communication. This allows the client access to the equipment connected to the RS232C 
port. 

In addition to a channel interface (§6.5.3), Pilot provides facilities to start and stop the 
RS232C channel code (§6.5.4), and to dial telephone numbers via RS366 dialing hardware 
associated with RS232C ports (§6.5.5). The RS232C facilities are implemented by the 
configuration RS232CIO. bed. 

6.5.1 Correspondents 

RS232CCorrespondents: definitions 

This interface defines the possible correspondents of the RS232C channel. Each 
correspondent is used to set certain line parameters. The interface also defines the 
different outcome possibilities of the auto recognition facility of the RS232C channel. 


6.5.1.1 Types and constants 
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RS232C.AutoRecognitionOutcome: type = RS232CEnvironment.AutoRecognitionOutcome; 

RS232CCorre$pondents.faiIure: RS232CEnvironment.AutoRecognitionOutCOme = ... 

RS232CCorrespondents.aSciiByteSync: RS232CEnvironm«nt.AutoRecognitionOutCOme = ... 

RS232CCorrespondents.ebcdicByteSync: RS232CEnvironment.AutoRecognitionOutCOme a . .. 

RS232CCorrespondents.bitSync: RS232CEnvironment.AutoRecognitionOutCOme ■ . .. 

RS232CCorrespondents.nsPfOtOCOl: RS232CEnvironment.AutoRecognitionOutCOme a . . 

RS232CCorrespondents.illegal: RS232CEnvironment.AutORecognitionOutCOme a . . . 

RS232CCorrespondents.xerOx800: RS232CEnvironment.Correspondent a .. . 

RS232CCorrespondents.xerOx850: RS232CEnvironment.Correspondent a .. . 

RS232CCorrespondents.SyStem6: RS232CEnvironment.Correspondent a „. . 

RS232CCorrespondents.cmd!: RS232CEnvironment.Correspondent a . .. 

RS232CCorrespondents.tty Host: RS232CEnvironment.Correspondent a .. . 

RS232CCorrespondents.nsSyStemElement: RS232CEnvironment.Correspondent a . . . 

RS232CCorrespondents.ibm3270HoSt: RS232CEnvironment.CorrespOndent a .. . 

RS232CCorrespondents.ibm2770Host: RS232CEnvironment.Correspondent a ... 

RS232CCorrespondents.ibm6670HoSt: RS232CEnvironment.CorrespOndent a . . . 

RS232CCorrespondents.ibm6670: RS232CEnvironment.Correspondent a ... 

RS232CCorrespondents.xerOx860: RS232CEnvironment.Correspondent a . . . 

RS232CCorrespondents.nsSyStemElementBSC: RS232CEnvironment.Correspondent a . 

RS232CCorrespondents.siemens9750: RS232CEnvironment.Correspondent a ... 

The correspondent implies information about the data formatting which the channel must 
perform, and should be set prior to data transfers. 

Note: xerox800 is not currently supported. 


6.5.1.2 Procedures 

RS232CCorrespondent.AutoRecognitionWait: procedure [channel: RS232C.ChannelHandle] 
returns [outcome: RS232C.AutoRecognitionOutcome]; 

If the line type in the parameter object (see §6.5.3.1) is set to autoRecognition, the client is 
asking the RS232C channel to attempt to determine as much as possible about the 
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correspondent at the other end of the communication line. The client should await the 
results of this auto-recognition attempt via a call to AutoRecognitionWait. 

Additional channel parameters, as appropriate to the outcome, may then be set by calls on 
SetParameter. The value illegal is returned if lineType has not been set to 

autoRecognition. 

Note: The auto recognition facility is not currently supported. A call to 

AutoRecognitionWait will always result in a outcome of illegal. 


6.5.2 Environment 

This interface defines the environment of the RS232C channel. This includes all the 
parameters of the line. 


6.5.2.1 Types and constants 

RS232CEnvironment.AutORecOgnitionOutCOme: TYPE a RECORD [[o..15]]; 

AutoRecognitionOutcome defines the range of possible results of the call to 
RS232CCorrespondents. AutoRecognitionWait. See §6.5.1 for the specific outcomes. 

RS232CEnvironment.CharLength: TYPE a [5..8]; 

This type defines the possible number of bits in a character. It pertains only to the data 
bits, and does not include start, stop or parity bits. 

RS232CEnvironment.CommParamHandle: type a pointer to RS232C.CommParamObject; 

RS232CEnvironrnent.CommParamObject:TYPE = RECORD [ 
duplex: RS232C.Duplexity r 
lineType: RS232CLineType f 
lineSpeed: RS232C.LineSpeed, 

accessDetail: select netAccess: RS232C.NetAccess from 
directConn a > null, 
dialConn a > [ 

dialMode: RS232cDialMode, 
dialerNumber: cardinal, 
retryCount: RS232C.RetryCount], 
endcase]; 

When an RS232C channel is created, it is necessary to specify a number of channel 
parameters. These parameters are supplied by means of CommParamObject. Additional 
characteristics of the channel are generally specified by calls to RS232C. SetParameter 
subsequent to the call to Create. 

duplex A half duplex line or a full duplex line is specified by duplex. 

lineType The lineType specifies the line type parameter necessary for creating 

the channel. It serves to define some general characteristics of the 
channel. Its choice is generally dictated by the equipment connected to 
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the RS232C port. For more detail on the effect of the lineType 
parameter, see section §6.5.3.4 on data transfer. 

lineSpeed lineSpeed is the line speed and its choice is dictated by the modem. 

accessDetail The accessDetail is the variant of the record that describes whether the 

network is the DDD network or a direct line network. For the dialing 
network, it determines how the phone is to be dialed and how many 
times the dial is to be attempted. 

RS232CEnvironment.Duplexity: TYPE = {full, half}; 

Duplexity defines the line as being full duplex or half duplex. 

RS232CEnvironment.CompletionHandle: TYPE [2]; 

The CompletionHandle identifies an action initiated by a RS232C.Get or RS232cPut. Each 
CompletionHandle must eventually be passed to a RS232C.TransferWait or 
RS232C.TransmitNow operation, which does not return until that particular activity is 
completed or aborted. 

RS232CEnvironment.Correspondent: TYPE ■ RECORD[[0..255]]; 

This type defines the range of correspondents. For specific correspondents, see §6.5.1. 

RS232CEnvironment.DialMode: type ■ {manual, auto}; 

DialMode defines how the phone is to be dialed. 

RS232CEnvironment.FlowControl: TYPE = MACHINE DEPENDENT RECORD [ 
type(O): {none, xOnXOff}, 
xOn(1), xOff(2): unspecified]; 

FlowControl specifies the flow control possibilities. 

Note: Flow control on the channel is currently not implemented. 

RS232CEnvironment.UneSpeed: TYPE = { 

bps50, bps75, bpsllO, bps134p5, bpsISO, bps300, bps600, bps1200, bps2400, 
bps3600,bps4800, bps7200, bps9600, bps19200, bps28800, bps38400, bps48000, 
bps56000, bps57600}; 

The LineSpeed defines the speed of the line. The choice is dictated by the modem. 

RS232CEnvironment.LineType: TYPE = { 

bitSynchronous, byteSynchronous, asynchronous, autoReeognition}; 

The LineType defines whether the line is bitSynchronous, byteSynchronous or 
asynchronous. A special line type of autoReeognition means the RS232C channel will 
attempt to determine as much as possible about the correspondent at the other end of the 
communication line. (For more detail on the effect of the line type, see the discussion 
following PhysicalRecord.) 
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RS 232 C. Net Access: type = {directConn, dialConn}; 

The NetAccess specifies the options for the connection types. It is used in the 

CommParamObject. 

RS232CnullLineNumber: cardinal * last [cardinal]; 

Used with the Pilot stateless enumerator RS232C.GetNextLine, nullLineNumber defines the 
starting and ending values of the enumeration. 

RS232CEnvironment.Parity: type * {none, odd, even, one, zero}; 

This type defines the parity to be used. 

RS232CEnvironment.PhysicalRecordHandle: type a pointer to PhysicalRecord; 

RS232CEnvironment.PhysicaI Record: type a record [header, body, trailer: Environment.Block]; 

The unit of information transferred across the RS232C Channel is the PhysicalRecord. 
The PhysicalRecord defines a frame of data consisting of an integral number of 8-bit bytes 
in the code set expected by the equipment connected to the RS232C port. The client may 
handle a frame as contiguous data, or may treat it as having up to three sections (header, 
body, trailer) which the channel will gather/scatter appropriately. 

As it travels between the client’s buffers and the communication line, certain elements of 
the frame are generated or stripped by the channel. Hence, the format of a frame at the 
interface between Pilot and the client is slightly different from the frame format as shown 
in the corresponding protocol documentation (e.g., BSC or HDLC). The 8-bit bytes are 
serialized across the the communication line with the following transformations according 
to the LineType (see §6.5.1.2), as well as the setting of various parameters (see 
SetParameter, §6.5.3.3): 

bitSynchronous (HDLC, SDLC, ADCCP): Flag patterns (01111110), and 

synchronization information are generated (on output) and stripped (on input) by the 
channel for all frames. Checksum information is generated (output) and checked (on 
input), bat not stripped , so the client's input buffer must provide two extra bytes. Zero 
insertion and removal following "11111" patterns is performed for all frames. On 
input, end-of-frame is defined by the recognition of a second flag pattern. On output, 
end-of-frame is defined by the Put procedure call. 

byteSynchronous Synchronization information is generated (on output) and stripped 
(on input) by the channel. Checksum information is generated (on output) and 
checked (on input) bat not stripped , so the client's input buffer must provide two extra 
bytes. On input, end-of-frame is determined by the client supplied parameter, 
correspondent (see §6.5.1.5). The channel generates or checks the checksum as 
implied by the value of this parameter. On output, end-of-frame is defined by the Put 
procedure call. In addition, a parity bit is (optionally) generated (on output) and 
checked/stripped (on input) by the channel for each byte. 

asynchronous (except when correspondent * tty Host): Checksum characters are 
generated (on output) and checked (on input) bat not stripped by the channel, so the 
client's input buffer must provide two extra bytes. On input, end-of-frame is 
determined by the client supplied parameter, correspondent (see §6.5.1.5). The 
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channel generates or checks the checksum as implied by the value of this parameter. 
On output, end-of-frame is defined by the Put procedure call. In addition, parity and 
start/stop bits are generated (on output) and checked/stripped (on input) by the 
channel for each byte. 

asynchronous (when correspondent = ttyHost): No checksum operations are 
performed. On input, end-of-frame is determined by a client supplied parameter: 
frameTimeout (see §6.5.1.5). On output, end-of-frame is defined by the Put procedure 
call, but has no other meaning. In addition, parity and start/stop bits are generated 
(on output) and checked/stripped (on input) by the channel for each byte. 

RS232CEnvironment.ReserveType: type a {preemptNever, preemptAlways, 
preemptlnactive}; 

RS232CEnvironment.RetryCount: TYPE a [0..7]; 

RS232CEnvironment. StOpBitS : TYPE = [1..2]; 

RS232CEnvironment.SyncCount: TYPE s [0..7]; 

RS232CEnvironment.SyncChar: TYPE a Environment. Byte; 

The following types have been added to support the multiport board and new 
encoding. They are the types of the new fields in the R$232C.Parameter. 

RS232CEnvironment.ClockSource: type = {internal, external}; 

RS232CEnvironment.EncodeData: type = {nrz, nrzi, fmO, fml}; 

RS232CEnvironment.ldleState: type = {mark, flag}; 

6.5,3 RS232C channel 

RS232C: definitions 

The RS232C channel provides the Pilot client with the lowest level access to the RS232C 
controller and its connected equipment. It assumes that the client has some familiarity 
with El A Standard RS-232-C. 

6.5.3.1 Types and constants 

RS232C.ChannelHandle: type [2]; 

The result of a successful RS232C.Create is a ChannelHandle, which is used for all 
subsequent channel operations. The handle becomes invalid after executing a 
RS232C. Delete, and subsequent use of it will have undefined results. 

RS232C.CharLength: type * RS232CEnvironment.CharLength; 

RS232C.CommParamHandle: type = RS232CEnvironment.CommParamHandle; 
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RS232C.CommParamObject: type = RS232CEnvironment.CommParamObject; 

RS232C.CompletionHandl6: type = RS232CEnvironment.CompletionHandle; 

RS232C.Correspondent: type ■ RS232CEnvironment.Correspondent; 

RS232C.DeviceStatus: type = RECORDfstatusAborted, dataLost, breakDetected, 
dearToSend, dataSetReady, carrierDetect, ringHeard, ringlndicator, 
deviceError: boolean]; 

The DeviceStatus defines the status of the RS232C device. It is accessed via 

RS232C.GetStatus and RS232C.StatusWait. 

statusAborted This status will normally be false on calls to RS232C.GetStatus. 

However, a call to RS232C.StatusWait may return because the 
channel was suspended, causing statusAborted to be set to true. 

breakOetected breakDeteeted is applicable only for lineType = asynchronous, 

and indicates that a break was received on the communication 
line. 

dearToSend, dataSetReady, carrierDetect 

These statuses correspond to states of circuits from the Data 
Communications Equipment (DCE) as described in EIA Standard 
RS-232-C. Normally, dataSetReady indicates that the data set 
(modem) is operational and connected to the communication line. 
dearToSend indicates that the data set is prepared to send data. 
On a full-duplex communication line, dataSetReady and 
dearToSend are normally always true following connection 
establishment, and need to be monitored only as exception 
conditions. On a half-duplex line, the normal scenario for use of 
these booleans is as follows: the client sets requestToSend, waits 
(via RS232C.StatusWait) until dearToSend is set, and then sends 
data (via RS232C.Put). When the client expects to receive data, he 
must clear requestToSend, so that the data set will allow the 
communication line to operate in the receive direction. 

deviceError This status is set true if a non-recoverable "shouldn’t happen" 

hardware or software error has occurred. 

RS232C.DialMode: type = {manual, auto}; 

The DialMode specifies the options for dialing used in the dialConn net access, used in the 

CommParamObject. 

RS232C.Duplexity: RS232CEnvironment.Duplexity; 

RS232C.FIowControl: type ■ machine dependent record [type(O): {none, xOnXOff}, 
xOn(1), xOff(2): unspecified]; 
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FlowControl defines the type of flow control the channel should perform. Currently, flow 
control is not implemented. 

RS232C.LatchBitClearMask: type = RS232C.DeviceStatus; 


Bits ringHeard, data Lost, and breakDetected are called latch bits in that they are set by 
the channel when the associated condition occurs, but are not cleared by the channel when 
the condition clears. They remain set to guarantee the client an opportunity to observe 
them. To clear them, a mask of type LatchBitClearMask must be defined, with the 
booleans corresponding to the proper latch bits turned on. 


RS232C.LineSpeed: type » 
RS232C.LineType: type = 
RS232C.NetAccess: type = 
RS232C.nullLineNumber: 


RS 232 CEnvironment.Li neSpeed; 
RS232CEnvironment.LineType; 
RS232CEnvironment.NetAccess; 
RS232CEnvironment.nullLineNumber; 


RS232C.Parity: TYPE 3 RS232CEnvironment.Parity; 

RS232C.OperationClass: type = {input, output, other, all}; 

The OperationClass specifies the different classes of operations which may be aborted by 
RS232C.Suspend. input consists of the Get operation only, output is Put and SendBreak, 
other is GetStatus and StatusWait. If the client wishes to abort all the operations, he may 
use the all option. 

RS232C.Parameter: type = record [select type: RS232C.ParameterType from 
charLength = > [charLength: RS 232 C.CharLength], 
dockSource ■ > [dockSource: RS232C.CIockSource], 
correspondent ■ > [correspondent: RS232C.Correspondent], 
dataTerminalReady * > [dataTerminalReady: boolean], 
echoing ■ > [echoing: boolean], 
encodeData = > [encodeData: RS232C.EncodeData], 
flowControl = > [flowControl: RS232C.FIowControl], 
frameTimeout * > [frameTimeout: cardinal], 
idleState a > [idleState: RS 232 C.ldleState], 
latchBitClear * > [latchBitClearMask: RS 232 C.LatchBitClearMask], 
lineSpeed a > [lineSpeed: RS232C.LineSpeed], 
maxAsyncTimeout a > [maxAsyncTimeout: cardinal], 
parity = > [parity: RS232C.Parity], 
requestToSend = > [requestToSend: boolean], 
stopBits = > [stopBits: RS232C.StOpBitS], 
syncChar = > [syncChar: RS232C.SyncChar], 
syncCount = > [syncCount: RS232C.SyncCount], 
endcase]; 

RS232C.ParameterType: type a {charLength, correspondent, dataTerminalReady, echoing, 
flowControl, frameTimeout, latchBitClear, lineSpeed, parity, requestToSend, stopBits, 
syncChar, syncCount}; 
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The RS232C.Parameter contains the following additional channel parameters: 


charLength 


clockSource 


correspondent 


The number of data bits in a character is specified by 
charLength. The number of bits, right justified, are removed 
from and stored into the 8-bit bytes described by 
RS232C.PhysicalRecord. Remaining bits are ignored on Put 
operations, and set to zero on Get operations. 

The source of the clock (from internal baud rate generator 
or from the external source)~default for asynchronous is 
internal, default for bit synchronous and byte 
synchronous is external. 

correspondent is the type of correspondent the client is 
communicating with, which is used to set certain channel 
characteristics. See §6.5.1.1 for the legal 

RS232CCorrespondents. 


dataTerminalReady This parameter corresponds to the state of the DTR circuit to 

the Data Communications Equipment (DCE). It should be set 
by the client as described in EIA Standard RS-232-C. 
Normally, dataTerminalReady is set to false when the client 
wishes to disconnect the communication line. 

echoing specifies whether echoing of input characters should 
be done by the RS232C channel. If echoing is true, all input 
characters received will be echoed by the RS232C channel. If 
it is FALSE, the client using the RS232C channel is responsible 
for echoing input characters. 

A parameter that may be used with SDLC. The default 
for any line type is nrz. 

flowControl specifies whether the channel should perform 
flow control. If type is xOnXOff , the RS232C channel will stop 
output when it receives an xOff character and resume output 
when it receives an xOn character. Note: flowControl is 
currently not implemented. 

frameTimeout The intra-frame timeout in milliseconds is specified by 

frameTimeout. On input, for all settings of parameter 
correspondent other than ttyHost, if the last byte of a frame 
does not arrive within frameTimeout milliseconds of the first 
byte, the frame will complete abnormally with status equal to 
frameTimeout. If the correspondent is set to ttyHost, then 
once the first byte of the frame arrives, if the next byte does not 
arrive within frameTimeout milliseconds, the frame will 
complete normally. Setting frameTimeout to zero is 
equivalent to setting an infinite frame timeout. 

idleState The state of the line when it is idle; i.e., whether to 

transmit flags or mark. The default for bit synchronous is 


echoing 


encodeData 

flowControl 
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flag; default for byte synchronous and asynchronous is 

mark. 

latchBitClear The mask used for clearing the latch bits of the 

RS232C.OeviceStatus is defined by latchBitClear. Only the latch 
bits which are set in this mask will be cleared. 


lineSpeed The speed of the line is defined by lineSpeed. Its choice is 

dictated by the modem. 


maxAsyncTimeout 


parity 

requestToSend 


stopBits 


syncChar 


syncCount 


Used in conjunction with frameTimeout for multiport 
asynchronous frame timing-default is 0 (infinite timeout). 

parity specifies the type of parity to be used. 

requestToSend corresponds to the state of the RTS circuit to 
the Data Communications Equipment (DCE). It should be set 
by the client as described in El A Standard RS-232-C . For full- 
duplex communication lines, it should remain true at all times. 
For half-duplex lines, it is used to control line turnaround. 
(See §6.5.3.1 for details). 

specifies the number of stop bits to use on the channel when 

lineType is asynchronous. 

specifies the synchronization character which the channel will 
transmit at the beginning of each frame when lineType is 
byteSynchronous. On input, synchronization characters 
preceding frames are discarded. 

is the number of synchronization characters which the channel 
will transmit at the beginning of each frame when lineType is 
byteSynchronous. On input, synchronization characters 
preceding frames are discarded. 


Not all parameters nor all syntactically legal parameter values are valid for all LineTypes. 
The following chart shows the valid values (as well as the default values) following calls to 

Create or SetLineType. 

Valid and Default Parameter Settings 



asynchronous 

byteSynchronous 

bitSvnchronous 

charLength 

any 1 (8) 

7,8 3(8) 

any (8) 

correspondent 

xerox800, ttyHost 

xerox850,system6, 

nsSystemElement 


(xerox800) 

cmcll (system6) 
siemens9750 

(nsSystemElement 

dataTerminalReady 4 

any (FALSE) 

any (false) 

any (FALSE) 
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echoing 

invalid 2 

invalid 

invalid 

flowControl 

invalid 

invalid 

invalid 

frameTimeout 

any (infinite) 

any (infinite) 

any (infinite) 

lineSpeed 

any (bps1200) 

any (bps1200) 

any (bps1200) 

parity 

any (none) 

any (none) 

any (none) 

requestToSend 4 

any (FALSE) 

any (false) 

any (false) 

stopBits 

any (1) 

invalid 

invalid 

syncChar 

invalid 

any (62B) 

invalid 

syncCount 

invalid 

any (2) 

invalid 


1. "any” means any syntactically-accepted value is valid. 

2. "invalid” means either the parameter is ignored, error RS232C.UnimplementedFeature or error 
RS232C.inva!idParafneter will be generated. See §6.5.3.2 for more information on these errors. 

3. charLength = 8 with parity = none is valid, and charLength = 7 with parity#none is valid. All other 
combinations are invalid. 

4. Default values are set following calls to RS232C.Create. Values are unchanged following calls to 

RS232C.SetLineT ype. 

RS232C.StOpBitS: TYPE = RS232CErtvironment.StOpBitS; 

RS232cPhysicalRecordHandle: type = RS232CEnvironment.PhysicalRecordHandle; 

RS232C.PhysicalRecord: type = RS232CEnvironment.PhysicalRecord; 

RS232C.ReserveType: type ■ {preemptNever, preemptAlways, preemptlnactive}; 

The ReserveType is used to establish priority among clients contending for a line during a 
call to RS232C.Create. preemptNever is used by clients who wish to never attempt to gain 
ownership of a line already being used. preemptAl ways is used to always attempt to gain 
ownership of such a line, and clients using preemptlnactive will attempt to gain 
ownership only if the current channel is not active. 

RS232dransferStatus: type = {success, dataLost, deviceError,frameTimeout, 

checksumError, parityError, asynchFramingError, invalidChar, invalidFrame, aborted, 
disaster}; 

TransferStatus describes the status of an individual data transfer (i.e., Get or Put). It is 
returned to the client as the result of the TransferWait or TransmitNow procedure. 

* success success is the status returned normally, when the data transfer has 

successfully completed. 
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dataLost This status will occur when a PhysicalRecord for a Get operation is not 

large enough to accommodate the arriving frame. The channel will 
discard all overflow data bytes until end-of-frame is detected. 

deviceError This status indicates the transfer should be considered successful, but 

a non-recoverable "shouldn’t happen” hardware or software error has 
occured.. Note that such status changes will cause the completion of 
any pending RS232C.StatusWait call (see §6.5.3.5 ). The dataLost latch 
bit will be set in the DeviceStatus record if data arrives when no 
PhysicalRecord has been allocated via a Get operation, and deviceError 
will be returned as the TransferStatus on all data transfer operations 
until the dataLost latch bit is cleared. 


frameTimeout frameTimeout is set if the last byte of a frame does not arrive within 
the timeout specified in the frameTimeout parameter in 

RS232C.Parameter. 


checksumError, parityError, asynchFramingError 

These states all imply that the data has not been transferred faithfully 
(i.e., stop bits are missing). 

invalidChar, invalidFrame, disaster 

These states are not implemented. 

aborted aborted will occur if RS232C. Suspend is called while the data transfer 

is outstanding. 


6«5.3.2 Signals and errors 

RS232C.ChannellnUse: error; 

If the channel is active and reservation (pre-emption) fails, this error is generated. 

RS232C.ChannelSuspended: error; 

After doing a RS232C.Suspend on a certain class of operations, a call to any operation in 
that class will result in the ChannelSuspended error being raised. 

RS232GlnvalidLineNumber: error; 

InvalidLineNumber is generated when the lineNumber supplied to the Create procedure is 
invalid. 

RS232C.lnvalidParameter: error; 

Generated by RS232C.Create or RS232C.SetParameter, this error indicates the client specified 
an invalid channel parameter. 

RS232C.SendBreaklliegal: error; 
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This error is raised when a client attempts to call the SendBreak procedure on a channel 
with a line type of byteSynchronous. 

RS232C.NoRS232CHardware: error; 

This error indicates the Create procedure has been called with no RS232C hardware 
installed. 

RS232C.UnimplementedFeature: error; 

UnimplementedFeature may be raised by a call to SetParameter, SetLineType, or Create. 

6.5.3.3 Procedures for creating and deleting channels 

RS232C.Create: procedure [lineNumber: cardinal, 

commParams: RS232C.CommParamHandle, preemptMe: RS232C.ReserveType] 
returns [channel: RS232C.ChannelHandle]; 

Each RS232C channel is a non-shareable resource that supports one full-duplex 
communication path. A channel is potentially contended for by Communication software 
and by Pilot clients accessing foreign devices. The RS232C channel resolves contention 
for and supports pre-emptive allocation. Clients call the Create procedure to reserve a 
channel. The channel handle returned is then used in all subsequent operations. If this 
procedure is called when no RS232C hardware is installed, the error 
RS232C.NoRS232CHardware will be raised. 

lineNumber The lineNumber specifies the RS232C line to use, 

which may be obtained using the GetNextLine 
procedure. If lineNumber does not represent a line 
present on the RS232C controller, the error 
RS232C.lnvalidLineNumber will be raised. 

preemptOthers, preemptMe These parameters serve to establish priority among 

contending clients. The state of a channel will be 
either inactive (available or waiting for a connection) 
or active. If a channel is available then a Create will 
always succeed. Otherwise, the success of the Create 
depends on the relative priorities of the current 
"owner” of the channel and the client trying to reserve 
it. If the channel is active and reservation (pre¬ 
emption) fails, the error RS232C.Channeilnllse is 
generated.The following matrix defines the result of a 
Create given the values of the owner’s preemptMe and 
the reserver’s preemptOthers. 


Owner’s preemptMe 




Never 

If Inactive Always 


Never 

Fail 

Fail Fail 

Reserver's 

preempt¬ 

If Inactive 

Fail 

Pre-empt* Pre-empt 

Others 

Always 

Fail 

Pre-empt Pre-empt 
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* Pre-empt if inactive 


A new reservation that is waiting for a connection has 
a grace period starting when Create is called and 
ending after a certain time interval, during which it is 
not considered to be inactive. During this time it is not 
pre-emptable by a client specifying a preemptOthers 
equal to preemptlnactive. This is necessary to prevent 
thrashing of contending listening clients who specify 
preemptMe equal to preemptlnactive. 

Caution: The grace period after a Create referred to 
above is not implemented in this version of Pilot. 

It is the responsibility of the client who called 
RS232C.Create to release the channel when the channel 
is pre-empted, or it is no longer required. Pre-emption 
is detected by noticing that all RS232C calls return a 
status of aborted. The pre-emption algorithm assumes 
that the channel owner will notice this, and cooperate 
by releasing the channel by doing a RS232C. Delete. 

commParams commParams specifies the basic channel 

characteristics. 

R$232C.SetParameter: procedure [channel: RS232C.ChannelHandle, 
parameter: RS232cParameter]; 

Additional channel parameters may be set by calling SetParameter. 

RS232C.Delete: procedure [channel: RS232cChannelHandle]; 

This operation has the effect of calling R$232CSuspend, aborting all pending activity on the 
channel. Any incomplete asynchronous activities (i.e., those initiated via Get or Put) will 
be terminated immediately with status = aborted. Note that it is the clients 
responsibility to call TransferWait or TransmitNow for each of these asynchronous 
activities in order for the call to Delete to complete. In general, this means that the Delete 
and the TransferWaits must be issued from separate processes. If the client wishes to 
terminate all pending activities normally, he should complete a call to RS232C.TransferWait 
or RS232C.TransmitNow for each pending activity before calling Delete. Upon return from 
the call to Delete, the CharmelHandle is invalid, and further calls using this handle will 
have undefined results. One convenient way to idle-down the channel is to set flags for all 
processes which have access to the ChannelHandle, call RS232C.Su$pend[all], and then join 
these processes prior to calling Delete. The assumption is that any process receiving an 
aborted status on an RS232C operation will check the flags and terminate. 

6.S.3.4 Data transfer procedures 

The operations described below transmit information to and from the equipment 
connected to the RS232C port. 
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RS232C.Get: procedure [channel: RS232C.ChannelHandle, 

rec: RS232C.PhysicalRecordHandle] returns [RS232C.CompletionHandle]; 

The Get operation queues the Physical Record for input transfer and returns to the client 
with the input transfer pending. The handle obtained via the RS232C.Create procedure is 
specified by channel, rec is the input buffer for the incoming data frame. 

RS232C.Put: procedure [channel: RS232C.ChannelHandle, 

rec: RS232C.PhysicalRecordHandle] returns [RS232C.CompletionHandle]; 

The Put operation queues the PhysicalRecord for output transfer and returns to the client 
with the output transfer pending. Both Get and Put are asynchronous , in the sense that 
they return to the caller as soon as the request has been queued, but complete at a later 
time. For each direction (i.e., input and output), pending activities are processed and 
completed in the order in which they are issued. The returned CompletionHandle 
identifies an activity initiated by a Get or Put operation. Each CompletionHandle must 
eventually be passed as a parameter to the TransferWait or TransmitNow operation, 
which does not return until that particular activity is completed or aborted. 

channel The handle obtained via the RS232C.Create procedure is specified by 

channel. 

rec rec is the output buffer for the frame of data to be sent. 

The I/O buffers described by the PhysicalRecord must not be released, altered, or re-used 
until after the TransferWait or TransmitNow operation for the associated transfer 
completes. 

RS232C.TransferWait: procedure [channel: RS232C.ChannelHandle, 
event: RS232cCompletionHandle] 

returns [byteCount: cardinal, status: RS232cTransferStatus]; 

Forking a process to perform a TransferWait allows the client program to proceed with 
parallel processing. 

channel channel is the handle obtained via the RS232C.Create procedure. 

event event is the completion handle that identifies the activity upon which 

to wait, {i.e., the handle returned from the Get or Put data transfer 
operation.) 

byteCount The number of data bytes transferred upon completion of the call is specified 
by byteCount. 

status The status of the completed call is specified by status. See §6.5.3.1 for 

the different status values that may be returned. 

TransferWait awaits completion of the activity initiated by Get or Put and returns to the 
client the number of bytes transferred and the status. For Puts, the return from this 
procedure indicates that the client’s buffers are available for reuse, but does not guarantee 
that the associated data has been transmitted on the communication line. 
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RS232C.TransmitNow: procedure [channel: RS232cChannelHandIe, 
event: RS232C.CompletionHandle] 

returns [byteCount: cardinal, status: RS232cTransferStatus]; 

Instead of Transfer Wait, TransmitNow may be used to force Put operations to complete. 
Return from this procedure guarantees that the data has been transmitted on the 
communication line. 

RS232C.Suspend: procedure [channel: RS232C.ChannelHandle f 
class: RS232C.OperationClass]; 

This procedure aborts all pending activity of the specified OperationClass and causes 
subsequent calls to generate the error R$232C.ChannelSu$pended until a call to Restart is 
issued. 

Suspend does not return until the abort of all pending activities of the specified 
OperationClass is complete. In the case of asynchronous operations it is the client’s 
responsibility to call TransferWait or TransmitNow for each of these operations in order 
for the call to Suspend to complete. In general, this means that the Suspend and the 
TransferWait must be issued in separate processes. Since Delete and SetLineType have 
the effect of a call to Suspend, this is also true of calls to them. 

RS232C.Restart: procedure [channel: R$232C.ChannelHandle, 
class: OperationClass]; 

This operation clears the effect of a call to Suspend. A suspend may occur as a result of an 
explicit Suspend operation or as a result of the occurrence of a sufficiently serious error. 


6.5.3.S Utility procedures 

RS232cGetNextLine: procedure [lineNumber: cardinal] 
returns [nextline: cardinal]; 

RS232C line numbers may be obtained by the GetNextLine procedure, a Pilot stateless 
enumerator with starting and ending values of nullLineNumber. 

RS232cGetStatus: procedure [channel: RS232cChannelHandle] 
returns [stat: RS232C.DeviceStatus]; 

In addition to the status information returned for each data transfer operation, Pilot 
maintains global information about the device itself. It is accessed via the GetStatus and 
StatusWait procedures. GetStatus returns the current status of the device. 

RS232C.StatusWait: procedure [channel: RS232C.ChannelHandle, 
stat: RS232cDeviceStatus] returns [newstat: RS232cDeviceStatus]; 

StatusWait waits until the current DeviceStatus differs significantly from the supplied 
parameter stat. Changes in status to statusAborted, dataLost, breakDetected, 
clearToSend, dataSetReady, carrierDetect and ringHeard are defined to be significant. A 
change to ringlndicator is not. The client must examine the device status to determine 
what action to take. 
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RS232C.SetLineType: procedure [channel: RS232C.ChannelHandle, 
lineType: RS232C.LineType]; 

SetLineType is used to change the LineType subsequent to creating the channel. Note that 
the process of deleting a channel and then creating it again has the effect of setting 
dataTerminalReady to false, thereby hanging up a switched telephone line connected to 
the modem. A call to SetLineType does not have this effect. 

The SetLineType operation has the effect of a call to RS232C.Suspend. If the client wishes to 
complete all pending activities normally, he should first call R5232C.TransferWait for each 
pending activity, prior to calling SetLineType. Parameter information (as supplied via 
prior calls to SetParameter) is reset to default values (see chart below), and should be 
resupplied. 

RS232C.SendBreak: procedure [channel: RS232C.ChannelHandle]; 

SendBreak transmits a break on the communication line, where break is defined to be the 
absence of a "stop” bit for more than 190 milliseconds if lineType equals asynchronous, or 
an abort (between 7 and 14 "1" bits) if lineType equals bitSynchronous. SendBreak is 
illegal for lineType equal to byteSynchronous, and will result in the error 
RS232C.SendBreak!llegal. Note that sending a break while data transfer operations are 
outstanding has unpredictable results. 

6.5.4 Procedures for starting and stopping the channel 

RS232CControl: definitions 

The RS232CControl interface allows the client to start and stop the RS232C channel code. 
When the configuration RS232CIO is started, the channel code is started. 

RS232CControi. Stop : procedure [suspendActiveChannels: boolean]; 

Stop stops the RS232C channel code. No new channel creations are allowed and any 
attempt to create a channel results in the error RS232C.NoCommunicationHardware. In 
addition, if suspendActiveChannels is true, all channels are suspended. 

RS232CControl.Start: PROCEDURE; 

Start allows channel creation after a Stop call. 

RS232C.NoCommunicationHardware: error; 

This error is raised when a client attempt to create a channel after RS232C.Stop has been 
called. 

6.5.5 Auto-dialing 

Dialup: definitions 

The Dialup interface allows the client to specify a telephone number for the auto-dialing 
hardware to dial. Upon successful completion of the dialing operation, data transfers 
across the associated RS232C channel will be directed to the equipment answering the 
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telephone call. (Note that the hardware association between modems and dialers is 
configured by the user, and is assumed to be known to the client of the Dialup and RS232C 
interfaces.) To cause a telephone number to be dialed, the client calls 

Diaiup.Dial: procedure [dialerNumber: cardinal, number: long pointer to Number, 
retries: RS232C.RetryCount,dialerType: oiaiup.DialerType] returns [Diaiup.Outcome]; 

Dialup.Number: type = record [number: packed sequence n: cardinal of Environment.Byte]; 

Dialup. RetryCount: type * [0..7]; 

Diaiup.Outcome: type s {success,failure,aborted,formatError,transmissionError, 
dataLineOccupied, dialerNotPresent, dialingTimeout, transferTimeout }; 

Oiaiup.DialerType: type = {RS366, Ventel, smartmodem, other}; 

dialerNumber specifies a logical dialer number corresponding to a physical dialer attached 
to a port either on the local processor or the Xerox 872/873 Communication Server . 
Dialing operations will also require some form of logical identifier to distinguish among 
multiple modems serviced by the same dialer. 


number is a sequence of bit patterns representing the digits to be dialed. With the 
exception on the pause, the dialup implementation attaches no semantics to any of the bit 
patterns it receives - they are simply passed to the dialer hardware. It is the responsibility 
of the client to know what bit patterns represent special characters such as EON and SEP 
for his particular hardware.The Modem then has the responsibility for detecting Answer 
Tone. In the absence of the EON digit, transfer is made automatically upon detection and 
processing of Answer Tone. 

retries indicates how many times the Dialup routine will retry the dialing operation 
following failure outcomes (see below). 

The values of Outcome are to be interpreted as follows: 


success 


failure 


aborted 


The dialing operation was successful. For dialers capable of 
detecting answer tone, this means that the call was answered by 
a compatible modem and control was successfully transferred by 
the dialer to the associated local modem. For dialers not so 
equipped (i.e., when EON is used to control transfer to the 
modem), this means that all the digits in the number were 
dialed, and control was successfully transferred to the modem. 
Note that success refers to the dialing operation, and should not 
be taken to mean that the associated modem is ready to transfer 
data. This should be determined by examining dataSetReady 
and clearToSend in the RS232cDeviceStatus. 

The dialing operation resulted in no answer, a busy signal, or 
the telephone was answered by something other than a 
compatible modem (e.g., a human being). 

The dialing operation was aborted (via Dialup.AbortCail). 
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formatError The parameter number was formatted incorrectly. 

transmissionError The transfer of the dialing information to the dialing hardware 
did not succeed. This should not happen in normal operation, 
and indicates a hardware problem which should be investigated. 


dataLineOccupied The telephone line to which the dialing hardware is connected 
was off-hook. This situation indicates an operational problem 
which should be investigated. 

dialerNotPresent The dialer hardware did not respond. This situation indicates a 
hardware problem (or a lack-of-hardware problem) which 
should be investigated. 


dialingTimeout The dialer did not respond to a request during dialing. This 
situation indicates a hardware problem which should be 
investigated. 


transferTimeout No meaningful reply was received from the dialer following 
dialing the last digit. The dialer neither detected a failure (i.e., 
busy or not answer) nor successfully transferred control to the 
modem. This situation indicates a hardware problem which 
should be investigated. 


Dialup. AbortCalI: procedure [dralerNumber: cardinal]; 

If the client wishes to abort the dialing operation (from another process) prior to the return 
from Dial, he may call AbortCall, causing the call to Dial to return with an Outcome of 
failure. 

Diaiup.GetDialerCount: procedure returns [numberOfDialers: cardinal]; 

The procedure GetDialerCount returns the total number of RS-366 (dialer) ports available. 
Dialup.pause: Environment.Byte = LAST[Environment.Byte]; 


When passed in the parameter number, pause causes the dialer to wait 6 seconds before 
dialing subsequent digits, pause is designed to be used in place of SEP on dialers that 
cannot detect Dial Tone. This bit pattern does not actually get passed to the dialer 
hardware. 
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6,6 Courier 

The term remote procedure calling refers to a software framework that facilitates the 
design, implementation and documentation of distributed services. Remote procedure 
calling casts the network protocols that underlie distributed services into a model closely 
resembling the invocation of procedures in nondistributed programs. Thus a client request 
for some service resembles a procedure call, and the information returned by the service 
resembles the return from a procedure. 

Mesa clients of Courier are provided with a set of facilities that closely parallel those 
provided by Mesa running on a single machine. Just as Mesa provides powerful facilities 
for modelling and controlling the interaction of programs through type-safety and signals, 
Courier provides facilities for modelling and controlling the interaction of systems 
distributed among an arbitrary number of machines. The principal limitation of Courier is 
that it supports only a subset of the Mesa data types. 

6.6.1 Definition of terms 

The following terms are used throughout this section and have specific meanings in the 
Courier context. 

disjoint data 


parameter area 


remote program 

RPC 


server 


transport 


user 


6.6.2 Binding 

Courier provides mechanisms for late binding at both the user and server machine. The 
mechanisms are less rigorous than their Mesa counterpart, but they do exist. 


In general, any Mesa structure that causes Courier to access data 
outside the current parameter area is disjoint. Examples of disjoint 
data are StringBodys and arrays described by long descriptors. 

A segment of contiguous virtual memory that contains Mesa data 
types and is being processed by a description routine. Parameter areas 
are defined by a LONG pointer and a size. 

A remote program usually represents a complete service , and the 
remote procedures it contains represent the operations of that service. 

This is an acronym for remote procedure call . In this context is refers to 
the actual processing of arguments and results, that function being 
separate from bulk data , for instance. 

The Courier server is the Mesa Courier client that provides or exports 
a service. 

The transport is used by Courier to carry the remote procedure call 
messages and by clients to carry bulk data. The transport is in the 
form of a Pilot stream, and is usually assumed to be a Network stream. 

The Courier user is the Mesa Courier client that requests, consumes or 
imports a service. 
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6.6.2.1 Binding to a service 

Binding at the user machine is controlled by the procedures Courier.Create and Delete and 
the existence of a valid Courier.Handle. The handle (and thus the binding) returned by 
Create remains valid on the machine it was created until it is deleted or the system is 
restarted. 

Courier. SystemElement: type ■ System. NetworkAddress; 

Courier. Handle: TYPE = LONG POINTER TO READONLY Courier.Object; 

Courier. Object: type » record [remote: Courier. SystemElement, 
programNumber: long cardinal, versionNumber: cardinal, 
zone: uncounted zone, sH: stream. Handle, 
classOfService: Networkstream.ClassOf Service]; 

Courier.Create: procedure [remote: Courier. SystemElement, 
programNumber: long cardinal, versionNumber: cardinal, 
zone: uncounted zone, classOfService: Networkstream.ClassOfService] 

RETURNS [Courier.Handle]; 

Courier.Delete: PROCEDURE [cH: Courier.Handle]; 

Courier.Error: error [errorCode: Courier.ErrorCode]; 

Courier. ErrorCode: type • {..., invalidHandle,...}; 

Successful completion of the Create procedure results in the returning of a Courier.Handle. 
The holder of that handle is then declared to be bound to the remote service specified. The 
service in turn is specified as a concatenation of a Courier.SystemElement, a remote 
program number and a desired version. Courier.Create also records other (interesting) 
aspects of the client's access to the remote service, namely the uncounted zone to be used 
for storing disjoint data structures, and an indication of the type of transport needed to 
effectively communicate with the service. 

Note: Create merely records the request for binding locally. Thus it may not do all the 
checking that one would expect. The first attempt to establish a dialogue with the remote 
service, hence completing the binding, is not made until the first Courier.Call (see §6.6.3). 

Note: The transport used by Courier for communication with the remote machine is 
(usually) under full control of Courier itself. The transport may be shared by other Courier 
clients, created or deleted at Courier’s discretion. Therefore the binding does not include 
the transport (except when it is being used by bulk data transfer (see §6.6.5)). 

The success of Create results in the caller possessing a Courier.Handle, and, indirectly, the 
Courier.Object to which it points. The only information in the object not provided by the 
client is a Stream.Handle, used by BuIkData (see §6.6.5). The possession of the Courier.Handle 
entitles the holder to make procedural requests, one at a time, of a remote service. The 
handle remains valid until explicitly deleted (Courier.Delete). Once deleted, the handle is 
void and may not be used in any operation (including Delete) again. Attempts to use an 
invalid handle will result in the signal Courier.Error[invalidHandle] being raised. 
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Note: Delete doesn’t delete the transport immediately. Courier will retain the transport 
for some period of time hoping another client will be able to use it, thus eliminating the 
overhead of deleting and creating the transport. Courier goes to great pains to (properly) 
utilize the transport, which is perceived to be very heavy-weight relative to the needs of 
most RPC operations. Delayed creates, reusing existing transports, and delayed deletes 
are all attempts to optimize the transport’s use. Regrettably, it also reduces the 
debuggability by at least an order of magnitude. 

6.6.2.2 Server binding 

Courier.ExportRemoteProgram: procedure [ 

programNumber: long cardinal, versionRange: Courier.VersionRange, 
dispatcher: Courier.Dispatcher, serviceName: long string nil, 
zone: uncounted zone, classOfService: Networkstream.ClassOfService]; 

Courier.VersionRange: type = record [low, high: cardinal]; 

Courier.Dispatcher: type = procedure [ 

cH: Courier.Handle, procedureNumber: cardinal, 
arguments: Courier.Arguments, results: Courier.Results]; 

Courier. Arguments: type = ... 

Courier.Results: TYPE * ... 

Courier. ErrorCode: type = {..., duplicateProgramExport, 

Courier.NoSuchProcedureNumber: error; 

In order to make a service available on a machine, the server client must first register that 
service (export) via ExportRemoteProgram. That action provides a template needed by 
Courier to complete the binding process as is it needed. It registers information about the 
service ( program number , version range , class of transport and the UNCOUNTED ZONE) much 
like Courier. Create. One difference is that the client specifies a version range when 
registering the service. This permits servers to provide backwards compatibility by 
allowing a single export to support any number of versions. Courier uses the information 
provided by the call as information to fabricate Courier. Handles (and the Courier. Objects 
behind them). Each handle thus created may be treated exactly as a handle returned by 
Courier. Create, with the exception that the lifetime of the handle is defined by Courier. The 
object is not created by a client and therefore should not be deleted by the client. It is 
assumed void when the client returns from his dispatcher. 

Courier will signal duplicate program exports (identical program number and version 
range) by raising Courier.Error[duplicateProgramExport]. Be aware that duplicate exports 
require an exact match. Registering a secondary export with overlapping version ranges 
will succeed, but will give non-deterministic results. 

The active part of the exported service is the client’s dispatcher. Courier calls this 
procedure from a forked process and in no way serializes incoming requests. The 
dispatcher is client-implemented and is responsible for the final stage of binding at the 
server machine. The last element in the binding process is the procedureNumber. The 
client must verify that the procedure is really exported by the service, and if it is not, it 
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should signal Courier.NoSuchProcedureNumber, thus rejecting the call. If the procedure 
number is valid, the service should proceed with the argument processing and perform the 
defined service. 

courier.UnexportRemoteProgram: procedure [ 

programNumber: long cardinal, versionRange: Courier. VersionRange]; 

Courier.ErrorCode: type = noSuchProgramExport,...}; 

Once registered via Courier. ExportRemoteProgram, the service is expected to respond to 
remote requests as the protocol for that service specifies. That responsiveness should 
continue until UnexportRemoteProgram is called. At that time, the service is no longer 
available and all subsequent requests will be rejected. UnexportRemoteProgram will not 
affect calls currently in progress. 

6.6.3 Remote procedure calling 

The major purpose of Courier is to provide a simple remote procedure call facility. It 
endeavors to relieve the client of many of the communications aspects of providing a 
remote service, leaving a call model that can be likened to Mesa in many respects. 

6.6.3.1 Client call 

Courier. Call: PROCEDURE [ 

cH: courier. Handle, procedureNumber: cardinal, 
arguments, results: courier.Parameters <- courier.nullParameters, 
timeoutlnSeconds: long cardinal «- last[long cardinal], 
requestDataStream: boolean «- false, 
streamCheckoutProc: procedure[cH: courier.Handle] <-nil] 
returns [sH: stream.Handle]; 

Courier.Parameters: type ■ record [location: long pointer, description: Courier.Description]; 
Courier.nullParameters: courier.Parameters = [nil.nil]; 

Courier.Description:....; 

Courier.ErrorCode: type ■ {..., 

transmissionMediumHardwareProblem, transmissionMediumUnavailable, 
transmissionMediumNotReady, noAnswerOrBusy, noRouteToSystemElement, 
transportTimeout, remoteSystemElementNotResponding, noCourierAtRemoteSite, 
tooManyConnections, invalidMessage, noSuchProcedureNumber, returnTimedOut, 
callerAborted, unknownErrorlnRemoteProcedure, streamNotYours, 
parameterlnconsistency, invalidArguments, noSuchProgramNumber, 
protocolMismatch, invalidHandle,...}; 

The basis of Courier’s RPC facility is embodied in the Courier.Call. Call completes the 
specification of the desired service by merging the binding information (cH), a procedure 
within that generic service (procedureNumber) and the parameters (arguments) to be 
supplied to the procedure. Due to the implied distributive nature of the call, the client is 
requested to provide an estimate of how much time will elapse before a response is 
declared lost (timeoutlnSeconds). The remaining two arguments (requestDataStream and 
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streamCheckoutProc) are relevant to bulk data transfer (see §6.6.5), as is the 
Stream. Handle returned by the Call. 


6.6.3.1.1 Call initial processing 

Courier.ErrorCode: type » {..., 

transmissionMediumHardwareProblem, transmissionMediumllnavailable, 
transmissionMediumNotReady, noAnswerOrBusy, noRouteToSystemEhement, 
transportTimeout, remoteSystemEIementNotResponding, noCourierAtRemoteSite, 
tooManyConnections, protocolMismatch, invalidHandle, 

Initial contact with the remote machine will be made when the first call is made to that 
machine. A transport will be created before the arguments are processed. That initial 
contact will not include information about the particular service involved in the procedure 
call. Thus, it establishes the ability to communicate with the remote machine but does not 
verify that the desired service is actually exported. 

Caution: Due to Courier's transport caching and swapping algorithms, it is almost 
impossible for a Courier client to tell when such initial contact is being established. 
Therefore, for the purposes of signal catching and the like, it is prudent to assume every 
Courier. Cal I is an initial contact. 


6.6.3.L2 Argument processing 

Courier.ErrorCode: type * {..., 

transportTimeout, invalidMessage, noSuchProcedureNumber, 
parameterlnconsistency, invalidArguments, noSuehProgramNumber, invalidHandle, 


Courier.VersionMismatch: error [versionRange: Courier.VersionRange]; 
Courier.VersionRange: type ■ record [low, high: cardinal]; 

The remote machine will be made aware of the full binding information during or 
immediately after processing the procedure’s arguments. Should the binding fail, Courier 
will raise Courier.Error with an appropriate error code (noSuchProcedureNumber or 
noSuehProgramNumber) or Courier.VersionMismatch. In the case of VersionMismatch, the 
user client is afforded the opportunity to select a version that is implemented by the server 
and retry the operation. 

Courier Call parameters are not an exact Mesa model of procedure parameters. As 
described in §6.6.6, Courier needs help to map Mesa data types to Courier data types. To 
provide that help, the Courier client must provide the location of the parameter area and a 
description routine to describe them in the form of a Courier.Parameters record. The 
Courier equivalent for a Mesa procedure with no arguments or results is a Courier.Call that 
has its arguments and results parameters assigned (or defaulted) a value of 
Courier. n u 11 Pa ra mete rs. 

Note: The description routine will not be called if either the location or the description 
field of the Parameters record is nil. 
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6.6.3.1.3 Waiting for results 

Courier. ErrorCode: type = {... f 

transportTimeout, returnTimedOut, unknownErrorlnRemoteProcedure,...}; 

Courier.RemoteErrorSignalled: error [ 

errorNumber: cardinal, arguments: Courier.Arguments]; 

Courier. Arguments: type ■ procedure [ 

argumentsRecord: courier.Parameters 4-Courier.nullParameters]; 

Once the arguments of a Call have been successfully transmitted, Courier will not return 
to the client until it either receives the results of the procedure call, receives notification 
that the call has failed, or abandons the call. During the period while Courier is waiting 
for the results, the transport is bound to the call. Should that transport fail, the local 
machine will abandon the call and raise the signal Courier.Error[transportTimeout]. 
Courier watches to insure that the call returns in a client specified period of time 
(timeoutlnSeconds). Should that time expire, Courier will raise the error 
Courier.Error[returnTimedOut]. 

Caution: timeoutlnSeconds must be translated to internal units by the underlying 
software. Should that conversion result in an overflow, the call will never timeout. The 
default of last[long cardinal] falls in this category. 

Note: Timing is begun after the user client returns from the streamCheckoutProc, or if it 
is nil, immediately after completing arguments processing. It does not include the time to 
create the transport, to process arguments, to transfer bulk data (see §6.6.5) or to process 

results. 

The server client may raise Courier.SignalRemoteError instead of returning results. This 
will translated to Courier.RemoteErrorSignalled at the user machine. The concatenation of 
the binding information and the errorNumber is equivalent to a unique Mesa signal and 
can be used to dispatch on proper code to process the signal’s arguments, which must be 
done by calling arguments with an appropriate Courier.Parameters record. Like a Mesa 
signal, once RemoteErrorSignalled is raised, the client should no longer expect the Call to 
return results as well. 

Caution: Courier.RemoteErrorSignalled’s arguments must be processed before UNWiNDing. 
To unwind would cause Courier to lose all the state being maintained for the call. 

Note: Like arguments or results, a signal with no arguments is a call to arguments with a 
parameter of Courier.nullParameters. 

Notes: Courier user clients must distinguish the difference between Courier.Error and 
Courier.RemoteErrorSignalled. The former is a Courier failure, while the latter is a (more 
useful) conveyance of status from a remote service. 
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6*6*3.L4 Freeing results 

Courier.Free: procedure [parameters: Courier.Parameters, zone: uncounted zone]; 

Any time Courier translates Courier data types to Mesa data types, it may be necessary 
for Courier to allocate storage for disjoint data structures. The storage will be allocated by 
Courier on the client’s behalf from the zone specified during the binding (Courier.Create[..., 
zone: UNCOUNTED ZONE,...]) using the standard Heap machinery. The client is responsible for 
deallocating these nodes, and to make that task easier, Courier provides the Free 
procedure. Once the client has processed the results, this procedure may be called, freeing 
all nodes allocated during the store (see §6.6.6) operation. 

Note: It is never wrong to call Courier.Free after processing the results, even if no storage 
was allocated in the store process. It is considered an optimization requiring knowledge of 
the Courier and Mesa data structures involved to not do so. 

6.6.3.2 Server’s dispatcher 

Courier.Dispatcher: type = procedure [ 

cH: Courier.Handle, procedureNumber: cardinal, 
arguments: Courier.Arguments, results: Courier.Results]; 

Courier. Results: TYPE = PROCEDURE [ 

resultsRecord: Courier.Parameters «-Courier.nullParameters, 
requestDataStream: boolean false] 

returns [sH: Stream.Handle]; 

The dispatcher is the server client’s link with the RPC mechanism. The dispatcher 
procedure is registered by the service implementor via CouHer.ExportRemoteProgram. 
When a user places a call, Courier will search its internal lists of exports for an 
appropriate export and call the registered dispatcher using a process spawned by Courier. 
The client dispatcher is passed information similar to that which the user client passes to 
Courier: a cH (Courier.Handle), a procedureNumber indicating the exact procedure 
requested from the service, and two procedures (arguments and results) that the client 
uses to link the appropriate parameter areas and description routines to the procedure’s 
parameters. 

6.6.3.2.1 Completing the binding 
Courier.NoSuchProcedureNumber: error; 

The dispatcher’s first responsibility is to complete the binding. The only unbound element 
is the procedureNumber. The dispatcher must verify that the cardinal number supplied is 
valid for the service, and if not, raise the signal Courier.NoSuchProcedureNumber. Once the 
dispatcher verifies that the procedure does exist, it is obligated to service the remote calls 
in the manner prescribed by the protocol it implements. 

6.6.3.2.2 Processing the remote procedure call 

The server client code first processes the arguments of a procedure by calling the supplied 
arguments procedure with an appropriate Courier.Parameters record. If there are no 
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procedure arguments, arguments must still be called with parameters of 
Courier.nullParameters. If actual arguments do exist, the location field of the Parameters 
record is assumed to point to an uninitialized but writable section of virtual memory. The 
argument data will be translated from Courier data types to Mesa data types with help 
from the description routine. 

After processing the procedure’s arguments, the service is expected to perform some 
predefined function, a function not known to Courier, and one that may include bulk data 
transfer (see §6.6.5). The byte stream is available (cH.sH) to the server client after Courier 
returns from arguments. The client is assumed to be finished with the stream when it 
calls results. 

When the service is complete, it must call results, either with a client defined parameter 
record or with Courier.nullParameters. The results returns a Stream. Handle. That handle 
will be nil unless requestDataStream is assigned a value of true. A non-NiL handle may be 
used for bulk data transfer. Client use of the stream in this case is assumed to be complete 
when it returns from the dispatcher. 

6.6.S.2.3 Freeing the arguments 

When storing (see §6.6.6) the arguments of a procedure call. Courier may allocate nodes of 
storage on behalf of its clients to store disjoint data structures. At sometime before 
returning from the dispatcher, the client must free that storage. This ntay be done as 
described in §6.6.3.1.4. 

6.6.4 Errors 

There is a considerable amount of error processing being performed by Courier. Most 
signals that might be raised by underlying implementations used by Courier are 
translated to Courier.Error with a (hopefully) meaningful errorCode. Other errors are 
implemented by Courier and may be raised by clients. 


6.6.4.1 Errors raised by Courier 

The following is a list of signals that Courier may raise and the client must catch. The 
discussions define the conditions under which they may be raised and suggest proper 
client reactions. 

Courier.Error: error [errorCode: Courier.ErrorCode]; 

Courier.ErrorCode: type a { 

transmissionMediumHardwareProblem, transmissionMediumUnavailable, 
transmissionMediumNotReady, noAnswerOrBusy, noRouteToSystemEIement, 
transportTimeout, remoteSystemElementNotResponding, noCourierAtRemoteSite, 
tooManyConnections, invalidMessage, noSuchProcedureNumber, returnTimedOut, 
callerAborted, unknownErrorinRemoteProcedure, streamNotYours, 
truncatedTransfer, parameterlnconsistency, invalidArguments, 
noSuchProgramNumber, protocolMismatch, duplicateProgramExport, 
noSuchProgramExport, invalidHandle, noError}; 
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This is the most common Courier signal. It should never be raised by and must always be 

caught by the client. Unless specifically noted, the following codes may be observed by 

both user and server clients. 

transmissionMediumHardwareProblem This is most likely to happen during initial 

attempts at establishing a connection, but could 
happen at any time. It is also most likely to be 
related to circuit oriented devices. At any rate, it 
is highly unlikely that anything can be gained 
by retrying the operation. Call your support 
personnel for assistance. 

transmissionMediumllnavailable Always associated with circuit oriented devices, 

it indicates that the device is either currently or 
permanently unavailable. One should check the 
hardware to verify its configuration, and if 
properly configured, retry at a later time. 

transmissionMediumNotReady Always associated with circuit oriented devices, 

suggests that the medium is operational, but 
unable to accept data. Possible remedies are to 
manually dial the phone or ready the modems. 

noAnswerOrBusy This error applies to circuit oriented media only 

and indicates that the local hardware was 
operational, but the remote either did not 
answer or was already busy. Retry at a later 
time (on the order of minutes). 

noRouteToSystemElement The network on which the remote machine 

resides is not reachable at this time. The 
internet may have been temporarily partitioned 
(due to system failure) such that the network is 
no longer reachable. Retry the operation at a 
later time (on the order of minutes). 

transportTimeout An active connection has suddenly become 

unusable. It may be due to the remote machine 
becoming inoperable or to an error prone 
connection somewhere in the internet. 

remoteSystemElementNotResponding Trying to establish a connection failed after a 

reasonable amount of time and attempts. Either 
the remote machine is inoperable or it does not 
exist on the specified network. Check the 
network topology and the state of the machine in 
question. This error will be observed only by 
user clients. 

noCourierAtRemoteSite Observed only at the user machine, an attempt 

to establish a connection with a remote machine 
succeeded, but it was found that Courier was not 
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listening , an indication that no services are 
exported by that machine. 

Courier has a limit as to how may transports it 
will support simultaneously. Creating the 
transport for this connection would exceed that 
limit. Try again at a later time (on the order of 
seconds). This error will only be observed on the 
user machine, but may reflect a condition on 
either the user of server machine. 

A message received from a remote machine was 
of the wrong format. This is an error in either 
Courier's or in the Courier client's protocol 
implementation. Retrying the operation will 
probably not be fruitful. This error will be 
observed only by user clients. 

noSuchProcedureNumber The remote service does not implement the 

procedure specified. This is a client protocol 
violation. Retrying will not help. This error will 
only be observed at the user. 

returnTimedOut A remote procedure call did not complete in the 

specified amount of time. Courier has 
abandoned the call. This could be due to an 
overloaded server, so retrying at a later time 
(minutes) may work. This error is observed only 
by user machines. 

callerAborted This error, observed only on server machines, 

indicates that the service has taken too long to 
formulate its reply. The calling machine has 
abandoned the call. The results cannot be 
delivered. The server never retries operations. 

unknownErrorlnRemoteProcedure Observed only at the user, an undefined error 

has occurred. The server machine's integrity is 
in doubt and retrying could compound the 
problem. 

streamNotYours A client of inter-call (§6.6.5.2) style bulk data 

transfer has attempted to call 
Courier.ReleaseDataStream when it did not have 
the stream checked out. If the client had 
previously used the (a) stream, the integrity of 
the Courier RPC transport is in doubt. The 
problem should rectify itself, but several RPCs 
may fail first. This is a client implementation 
error. 


tooManyConnections 


invalidMessage 
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truncatedTransfer 


parameterlnconsistency 


invalidArguments 


noSuchProgramNumber 


protocolMismatch 


duplicateProgramExport 


noSuchProgramExport 


This error code will only be observed by 
implementors of the bulk data transfer protocol 
Bulk data transfer protocol implementors are 
clients of the filtered byte stream provided by 
Courier for that purpose. That protocol requires 
that data be transmitted with a 
SubSequenceType other than 0. This error 
implies that the stream client attempted to 
consume some data of SubSequenceType of 0. 

Client parameter processing error. This is 
probably due to a malformed Mesa data item or 
an invalid implementation of the client’s 
protocol (in the description routine). In such 
cases is doubtful that retrying the operation will 
help, and it might hurt. It is also possible (but 
highly unlikely) that the transport has failed to 
deliver the data correctly. 

Either Courier or the client description routine 
has noted a discrepancy in the format of the 
arguments and raised Courier. InvalidArguments. 
Courier caught the signal and either sent a 
reject (if it was raised remotely) or translated it 
into a Courier.Error. 

The program number that the user wishes to 
bind to is not exported at the server in any 
version. Retrying will not be helpful. Verify that 
the correct machine is being accessed for the 
service desired. This error will only be observed 
on user machines. 

Observed only at the user during initial 
transport creations, indicates that the user and 
server are running incompatible versions of the 
Courier protocol. No retrying is in order. Check 
the network topology and the versions of 
software running at the respective machines. 

This error code is observed only when 
attempting to export a service. It indicates that 
the programNumber and versionRange 
parameters of Courier.ExportRemoteProgram 
matched exactly with those already known by 
Courier. 

This error code is observed only when 
attempting to unexport a remote service. It 
indicates that the programNumber and 
versionRange specified in the unexport request 
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(Courier.UnexportRemoteProgram) did not have 
an equivalent known to Courier. 

invalidHandle An operation requiring a Courier.Handle checked 

the handle and found it to be invalid. The handle 
was probably already deleted, or (even worse) 
never created. Don't retry the operation. 

noError This should never be observed by any Courier 

client. It is included to simplify internal 
processing. 

Courier.VersionMismatch: error [versionRange: courier.VersionRange]; 

The remote service version number is passed as part of every remote procedure call. If the 
Courier server discovers that the machine does export the program, but not the particular 
version, it will notify the user machine of the range of versions supported by the server. 
The user then has the option to observe that range, and if it implements a compatible 
version, to retry the operation with appropriate parameters. 

Note: This feature is only implemented for servers of Courier version 3 or higher. 

Couner.RemoteErrorSignalled: error [ 

errorNumber: cardinal, arguments: Courier.Parameters «-Courier.nullParameters]; 

RemoteErrorSignalled is Courier's equivalent to a Mesa signal. The signal is initiated in 
the signaller (server) machine by the client raising the signal Courier.SignalRemoteError 
(see §6.6.4.2), thus aborting the call. At the user, the abort message is used to reconstruct 
the context of the signal, renaming it Couner.RemoteErrorSignalled. The argument 
errorNumber of the signal permits the client to dispatch to the appropriate processing 
code. The remaining context of the signal must be retrieved by calling arguments. If the 
semantics of the signal indicate no arguments exist, then arguments should be called with 
a defaulted value of Courier.nullParameters. The arguments of the signal must be processed 
before the unwind is generated. 

6.6.4.2 Signals clients may raise 

Courier.NoSuchProcedureNumber: error; 

During the client dispatcher's final phase of binding, it may find that the 
procedureNumber, specified as one of the Courier.Dispatcher arguments, is invalid. It must 
then raise this signal, and Courier will transfer that information to the caller and reject 
the call. This signal must not be raised by the client except in the dispatcher. At the user 
the information will be translated to Courier. Error[noSuchProcedureNumber]. 

Courier.InvalidArguments: error; 

Client description routines may notice unacceptable parameters. If this is so, the client 
may raise InvalidArguments. This signal will be translated by Courier to 
Courier.Error[invalidArguments] at the user. Both server and user code may raise this 
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signal; the server will not translate the error locally, but it will reject the call, send the 
information to the user, where ErrorfinvalidArguments] will be raised. 

Courier.SignalRemoteError: error [ 

errorNumber: cardinal, arguments: Couner.Parameters ^Courier.nullParameters]; 

SignalRemoteError is the mechanism Courier client servers use to emulate the generation 
of a Mesa signal. Courier intercepts the signal and translates it into an abort message that 
includes the errorNumber and any additional arguments the client may have specified. If 
the semantics of the signal are that no arguments exist, arguments should be assigned (or 
defaulted) a value of Courier.nullParameters. 

Note: Courier will call the client's argument description routine before UNWfNDing from 
the catch phrase. 

6.6.5 Bulk data 

Courier supports applications whose communication requirements are primarily 
transactional in nature. However, not all network communication is transaction oriented. 
File transfer, for example, is more appropriately modelled as bulk data transfer. In order 
to blend this bulk transfer requirement with the transactional nature of remote procedure 
calling. Courier provides access to an established byte stream , permitting the client to use 
that byte stream for those applications that require it. 

6.6.5.1 Intra-call bulk transfer 
Courier.Call: PROCEDURE^.., 

streamCheckoutProc: procedure [cH: Courier.Handle], 

Courier. Object: type = record sH: stream. Handle,...]; 


The Courier user and server client have the stream made available via the Courier.Object 
that is in turn accessible through the Courier.Handle. The stream contained therein is 
slightly limited when compared to a generic Pilot stream. It may be used only between 
argument and result processing and it will not permit the client to set the Subsequence 
Type to a value of zero, nor will it permit the client to delete the stream. Attempts to do 
these will result in the error stream. InvalidOperation. 

Note: The client is responsible for processing all signals that might be raised by a Pilot 
stream. 


The user client is given control after the processing of the arguments if the 
streamCheckoutProc has a value other than nil. At the server, the client has control 
between the processing of the arguments and results and may use the stream at that time. 
The state of the stream provided the client is a default stream (i.e., timeout = 60 seconds, 
sst = 0, input options = Stream. defaultlnputOptions) It is assumed the client is finished 
with the bulk transfer when it returns from the streamCheckoutProc procedure (user) or 
calls results (server). The state of the returned stream is undefined and Courier expects to 
have to reset the parameters for its subsequent use. 
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6.6.5.2 Inter-call bulk transfer 

Courier. Call: procedure [..., requestDataStream: boolean, ...] 
returns[sH: stream.Handle]; 

Courier. Results; type a procedure [..., requestDataStream: boolean,...] 
returns[sH: Stream. Handle]; 

Courier.ReleaseDataStream: procedure [cH: Courier.Handle]; 

Courier. ErrorCode: type = {..., streamNotYours,...}; 


This version of bulk transfer provides the client with an unfiltered stream, unrestricted by 
Courier in any way, either as a result of the Courier.Call at the user or as a result of calling 
results at the server. If the parameter requestDataStream is false, the value returned for 
sH will be nil. If the parameter requestDataStream is true, the stream provided is a 
default stream as described in §6.6.5.1. The user client is assumed finished with the 
stream when he calls Courier.ReleaseDataStream. Attempting to release a stream that was 
never checked out will result in the error Courier.Error[streamNotYours] being raised. 
Until that time the transport cannot be used for any other purpose, including another 
remote procedure call. At the server Courier assumes ownership of the stream when the 
client returns from his dispatcher. The client may perform any stream operation desired 
except delete and those not supported by the transport (such as positioning in the case of 
Network streams). 

6.6.6 Description routines 

Courier description routines are used to translate Mesa data types to and from Courier 
data types. Courier provides the machinery to perform this translation process via a notes 
object passed by reference to each description routine. 

The notes object contains the context within which the description routine is operating. 

Courier. Description: type = procedure [notes: courier. Notes]; 

Courier. Notes: TYPE = POINTER TO Courier. NotesObject; 

Courier.NotesObject: TYPE = RECORD [...]; 

Courier requires client assistance to map Mesa data types into Courier data types. The 
client provides that assistance in the form of a description routine. Description routine 
procedures are of type Courier. Description. The notes object is passed by reference to all 
client description routines. It contains context about the process being performed and a 
series of procedures to perform the bulk of the work involved in mapping Mesa data types 
to and from Courier data types. 

6.6.6.1 Mesa data type restrictions 

The Courier Protocol supports a set of data types that closely corresponds to the set of 
common Mesa data types. Because the Courier Protocol is intended for a heterogeneous 
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internet, however, not all Mesa types are supported. Also, for those Mesa data types that 
are supported, there are a few restrictions that arise from the need to maintain a set of 
data types that are reasonably easy to support on other types of systems. 

Below are suggested mappings of Courier data types to compatible Mesa data types. Since 
Courier has a Mesa heritage, finding a semantically equivalent Mesa data type for every 
Courier data type is a fairly simple task. 


6.6.6.LI Fully compatible data types 

The following data types have equivalent representations in Courier and Mesa. 


Courier data type 


Corresponding Mesa data type 


CARDINAL 

INTEGER 

UNSPECIFIED 


CARDINAL 

INTEGER 

UNSPECIFIED 


6.6.6.1.2 Data type compatibility supported by Courier clients 


The following Courier data types have a representation in Mesa, but is not a common data 
type. Courier does not support the noting of these data types within the description 
routine. It is the responsibility of the Courier client to use the restricted form shown 
below. 


Courier data type Corresponding Mesa data type 

BOOLEAN MACHINE DEPENDENT RECORD [ 

zeros: [0..7777B], value: boolean] 

{idi(Vi), ... id n (v n )} MACHINE DEPENDENT 

{idi(vi), ... id n (Vn), LASTICARDINAL]} 
RECORDf/dj. Type 1f ... id n : Type n ] machine dependent record [ 

id i: Type h ... id n : Type n ] 

6.6.6.1.3 Data type compatibility supported by Courier via notes 

The following Courier data types have a representation similar to that of Mesa. The 
differences are resolved at the time the description routine notes instances of them. 

Courier data type Corresponding Mesa data type 

LONG CARDINAL 
LONG INTEGER 
LONG STRING 
array [0..n) OF Type 

MACHINE DEPENDENT RECORD [ 

id 0 : Type 0 , 
id i • Type h 

id n : select n from 
tag 0 3 > [Type n ], 
tagi 3 > [Type n + i], 

tag m = > [Type n + m ]] 

DESCRIPTOR FOR ARRAY OF Type 


LONG CARDINAL 
LONG INTEGER 
STRING 

array n of Type 
CHOICE n OF {list} 


SEQUENCE n of Type 
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6.6.6.2 Description context 

The notes object contains the context within which the description routine is operating. 

Courier.NotesObject: type = record [type: {fetch, store, free},...]; 

The first field of the notes object informs the client what type of operation is to be 
performed. The notes object procedures are designed such that most of the operations are 
performed as side-effects enabling a single description procedure to perform all three of the 
following operations without caring about the specific operation type. In some cases, 
however, the client needs to be aware of the current operation. 

fetch To fetch is to translate Mesa data types to Courier data types. This is 

sometimes referred to as serialization or marshalling of data. This 
action occurs when call parameters are processed by the user or when 
return parameters are processed by the server. 

store To store is to translate Courier data types to Mesa data types. This is 

sometimes referred to as deserialization or unmarshalling. This action 
occurs when call parameters are being processed by the server or when 
result parameters are being processed by the user. In such cases, 
Courier will allocate nodes of storage for disjoint data structures (long 
STRING, LONG DESCRIPTOR FOR array, DisjointData) from the current zone. 
In some cases, the client may wish (or have) to allocate nodes directly, 
as in the case of NoteSpace. 

free The Courier client is required to free the storage nodes allocated by 

Courier during a store operation. It is possible and recommended that 
the client do that via the Courier.Free operation. When a description 
routine is being called with type of free, the client has the opportunity 
to release nodes that he may have allocated unknown to Courier, such 
as nodes for the NoteSpace operation. 

Courier.NotesObject: type = record [..., zone: uncounted zone, ...]; 

The description client is also made aware of the heap that the program wishes to use to 
allocate or free storage. This field is a copy of the zone registered by the client during 
Courier.Create and CouHer.ExportRemoteProgram. The client will find that the zone field is 
most useful during storing and freeing operations. 

6.6.6.3 Data noting procedures 

Each note routine contained in the notes object is provided to perform mapping to and from 
explicit Courier and Mesa data types. Each routine has at least three properties. First, it 
has a specific Mesa to Courier mapping function. Second, it contains the site of the data 
being described. Third, the note procedure consumes an implicit amount of the parameter 
area. 
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6.6.6.3.1 NoteSize 

Courier.NotesObject: type = record [..., noteSize: Courier.NoteSize, ...]; 

Courier.NoteSize: type = procedure [size: cardinal] returns [site: long pointer]; 

The first responsibility of a description routine is to note the size of the record being 
described. This size (in words) coupled with the starting address of the record defines a 
parameter area whose contents must be noted, either explicitly through one of the data 
noting procedures supplied in the notes object , or implicitly by skipping over a portion of 
the parameter area with other explicit notes, or by returning from the description routine. 
No data noting procedures may be called before NoteSize and NoteSize may not be called 
more than once per description routine. 

6.6.6.5.2 NoteLongCardinal, NoteLonglnteger 

Courier.NotesObject: TYPE = RECORD [..., 

noteLongCardinal: Courier.noteLongCardinal, 
noteLonglnteger: Courier.noteLonglnteger,...]; 

Courier.NoteLongCardinal: type = procedure [ 
site: LONG POINTER to long CARDINAL]; 

Courier.NoteLonglnteger: type * procedure [ 
site: LONG POINTER to long integer]; 

All long cardinal and LONG integer data types contained in the parameter area must be 
explicitly noted. Two words are consumed from the parameter area with each call. 

6*6.6.3.3 NoteString 

Courier.NotesObject: type = record!..., noteString: courier. NoteString, ...]; 

courier.NoteString: type = procedure [site: long pointer to long string]; 

All long string data types contained in the parameter area must be explicitly noted. Two 
words are consumed from the parameter area with each call. Storage for the StringBody 
will be allocated from the notes object zone by the store operation. 

Note: The maxlength attribute of the Mesa StringBody will be lost in the fetching 
operation. Consequently, stored strings will always have a maxlength equal to the length. 

Caution: Strings that are NIL or have a length of zero when fetched are always stored as 
strings with zero length. The client must be aware that such stored strings are readonly. 
They must not be modified in any way. They must not be freed except by the Courier.Free 
operation. 
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6.6.6.3.4 NoteChoice 

Courier.NotesObject: type = recoro [..., noteChoice: Courier.NoteChoice,...]; 

Courier.NoteChoice: type = procedure [ 
site: long pointer, 
size: cardinal, 

variant: long descriptor for array of cardinal, 
tag: long pointer*-nil]; 

NoteChoice provides the Courier client with a somewhat restricted use of the Mesa 
variant record. In addition to the site parameter, the procedure call also specifies the 
undiscriminated length of the variant record. It is that length that will be consumed from 
the parameter area by the procedure call. The client is also required to supply an array 
descriptor for an array of variant record discriminated lengths. A fourth optional 
parameter specifies the address of the variant record's tag field. If that field is omitted, 
assigned a value of NIL, or a value equal to that of the site parameter, Courier assumes that 
the variant tag is the first element of the variant record. Otherwise it assumes a record 
with a static portion followed by a variant portion. 

Note: The variant tag must be word aligned and 16-bits wide. 

6.6.6.3.5 Note Array Descriptor 

Courier.NotesObject: TYPE s RECORD [..., 

noteArrayDescriptor: Couner.NoteArrayDescriptor,...]; 

Courier. NoteArrayDescriptor: type = procedure [ 

site: long pointer, elementSize, upperBound: cardinal]; 

This procedure notifies Courier that a Mesa long descriptor exists at site. The procedure 
call consumes three words of the parameter area. But since descriptors define disjoint data 
in the form of an array, the virtual memory defined by that array is not from the original 
(or current) parameter area. For that reason, another parameter area is fabricated using 
the descriptor's base and length, the latter being multiplied by the length of each element 
as passed by the client. The newly defined parameter area must be completely consumed 
before any more of the previous parameter area can be processed. For store operations, the 
storage for the parameter area will be allocated from the notes object zone. The last 
parameter, upperBound, is the maximum length that Courier should accept within the 
descriptor. 

Note: Descriptors having base = nil or length = 0 during the fetch will always be stored 

as descriptor(nil,o]. 

6.6.6.5.6 NoteDisjointData 

Courier.NotesObject: type * record!..., 

noteDisjointData: Courier.NoteDisjointData,...]; 
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Courier.NoteDisjointData: type = procedure [ 

site: long pointer to long pointer, description: Courier.Description]; 

NoteDisjointData permits the client to note data that is only referenced via a long pointer 
in the parameter area. It is provided as a convenience to clients to eliminate local copying 
of parameters or as data hiding mechanism. NoteDisjointData consumes two words from 
the parameter area. The second argument of the procedure is another description routine. 
Courier will call that routine, and it will in turn call noteSize. The beginning of the 
disjoint area and the size define an new parameter area. That parameter area will be 
allocated from the notes object zone during store operations. Pointers are not Courier data 
types. The pointer will be dereferenced and the dereferenced object processed during a 
fetch operation. An appropriate object will be allocated from the notes object zone and a 
pointer to that object will be placed in the client parameter area during store operations. 
No notion of a pointer (or its absence) will be conveyed to the storing machine by Courier. 

Caution: This scheme does not lend itself to processing of linked list and other recursive 
data structures that are associated via pointers. Linked lists may be processed if properly 
approached. Some other bit of information must be transmitted, usually a boolean, that 
indicates the last element of a list has been processed so the recursion can be broken by the 
storing client. 

6.6*6.3.7 NoteParameters 

Courier.NotesObject: TYPE = RECORD 

noteParameters: Courier.NoteParameters, ...]; 

Courier.NoteParameters: type = procedure [ 

site: long pointer, description: Courier.Description]; 

NoteParameters is much like NoteDisjointData except there is no pointer involved. The 
second argument of the procedure call is again a description routine. The closely following 
call to noteSize coupled with the site of the noteParameter defines a new parameter area. 
That new parameter area must be totally contained within the previous parameter area. 
In the former case the amount of space specified in the noteSize operation will be 
consumed from the current parameter area. 

6.6.6.3.8 NoteSpace 

Courier.NotesObject: type = record [...,noteSpace: courier.NoteSpace,...]; 

Courier. NoteSpace: type = procedure [site: long pointer, size: cardinal]; 

NoteSpace permits a Courier client to process a block of unspecified data. It does not 
define an new parameter area, hence no data can be noted within the space defined by 
NoteSpace The data is not linked to the parameter area in any way. Consequently, the 
store space must be allocated by the client, unlike other disjoint data types. The procedure 
call consumes no portion of the parameter area. 

Caution: NoteSpace does not cause unnoted data to be processed. The space being 
described is completely divorced from the current client parameter area. 
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6.6.6.3.9 NoteDeadSpace 

Courier.NotesObject: TYPE = RECORD [..., 

noteDeadSpace: Courier.NoteDeadSpace,...]; 

Courier.NoteDeadSpace: type = procedure [site: long pointer, size: cardinal]; 

NoteDeadSpace is used to consume a portion of the parameter area without generating 
any Courier data, just the opposite of NoteSpace. The amount of parameter area to be 
consumed is client specified. 

Note: NoteDeadSpace does cause unnoted data to be processed. Consequently, it is the 
procedure of choice used to force unnoted data to be processed (e.g., 
notes.noteDeadSpace[site f 0] will cause all unnoted data in the current parameter area to 
be processed and then consume zero more words of that parameter area). 

6.6.6.3.10 NoteBlock 

Courier.NotesObject: TYPE = RECORD [..., 
noteBlock: Courier.NoteBlock,...]; 

Courier.NOteBlOck: TYPE = PROCEDURE [block: Environment.Block],* 

NoteBlock provides Courier clients with a mechanism that enables them to process byte 
oriented data. This procedure will process only the bytes defined by the Environment.Block, 
and will consume nothing from the current parameter area. Nor will Courier allocate 
storage during store operations for the disjoint area implied by the operation. 

Caution: It is expected that this procedure will be used by clients as a building block for 
complicated description routines. When using NoteBlock such clients are responsible for 
insuring that an even number of bytes actually gets processed with each complete 
operation, even if it means appending a null byte to the end of a stream of bytes. Courier 
data types always begin on 16-bit (word) boundaries. 

6.6.6.3.11 Unnoted 

Unnoted data is a concept rather than a procedure. Parameter areas are represented 
internally and conceptually as ordered long pointers, constructed initially by the location 
parameter of a Courier.Parameters and the size parameter of a notes.noteSize procedure 
call. Subsequent parameter areas may be created when describing disjoint data structures 
(e.g., DisjointData, DescriptorForArray). All the data noting procedures specify a site that 
is an address within the bounds of a parameter area. The current data point within the 
record is known to be the last site specified plus the amount of data consumed by the last 
note procedure. The portion of the parameter area between that left edge and the current 
site is unnoted data and is processed as such, implying that the Courier and Mesa data 
types are compatible. 

6.6.7 Miscellaneous facilities 

Courier.SerializeParameters: procedure[ 

parameters: Courier.Parameters, sH: stream.Handle]; 
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Courier.DeserializeParameters: procedure! 

parameters: Courier.Parameters, sH: stream.Handle, zone: uncounted zone]; 

These two procedures provide access to the description routine facilities of Courier outside 
the bounds of a remote procedure call. SerializeParameters performs a fetch operation, 
converting Mesa data types defined by the parameters record to Courier data types and 
putting them on the stream defined by sH. The client is responsible for all signals that may 
be raised by the stream implementation. DeserializeParameters is the counterpart of 
SerializeParameters. It performs a store operation, converting Courier data types gotten 
from the stream sH to Mesa data types defined by the parameters record. Since this is a 
store operation, Courier may have to allocate storage for disjoint data structures. If so, the 
storage will be allocated from zone. As with any store operation, the client assumes 
responsibility for that storage and may deallocate it via Courier. Free. 

Courier.LocalSystemElement: procedure RETURNSfcourier.SystemElement]; 

This procedure returns a full network address of the local machine. The socket field of the 
address will always be Courier’s well-known socket. 

Courier.EnumerateExports: procedure returns! 
enum: long descriptor for Courier. Exports]; 

Courier.FreeEnumeration: procedure! 

enum: long descriptor for courier.Exports]; 

Courier. Exports: TYPE = ARRAY CARDINAL OF Courier.ExpOrtltem; 

Courier. Exportltem: TYPE = MACHINE DEPENDENT RECORD! 
programNumber: long cardinal, 
versionRange: courier. VersionRange, 
serviceName: long string, 
exportTime: System.GreenwichMeanTime]; 

EnumerateExports will make a copy of the current internal structures representing the 
results of all previous Courier.ExportRemoteProgram requests. With one exception the 
elements of the array returned were supplied by the ExportRemoteProgram client. The 
exception, exportTime, is the time that the ExportRemoteProgram request was made. The 
storage for the enumeration array is allocated from a zone internal to Courier, so the client 
is obligated to free that space at some time, which he may do with 
Courier.FreeEnumeration. 
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This chapter contains those facilities, usually Common Software packages, that are 
concerned primarily with formatting and editing. §7.1 describes an interface that defines 
some common ASCII characters; §7.2 describes a package for converting between some 
common Mesa types and strings; §7.3 discusses the standard string processing procedures; 
and §7.4 describes operations for converting between strings and Pilot's internal form of 
time. 

7.1 ASCII character definitions 

Ascii: definitions ; 

The Ascii package consists only of a definitions file. 

All of the control characters of the form control uppercase-letter are defined in the form: 
Ascii.Control uppercase-letter-, character = 'uppercase-letter - 1008, 

For example, 

Aseii-ControlB: CHARACTER = 'B - 100B; 

In addition, a few special control keys are defined as their commonly used names: 

Ascii.BEL: CHARACTER 3 G-1008; 

Ascii. BS: CHARACTER = H - 100B; 

Ascii. CR: CHARACTER = 'M - 100B; 

Ascii.DEL: CHARACTER = 177C; 

Ascii. ESC: CHARACTER = 33C, 

Ascii.FF: CHARACTER = 'L - 100B; 

Ascii.LF: CHARACTER = J - 100B, 
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Ascii.NUL: CHARACTER = OC; 
Ascii.SP: CHARACTER = ’ ; 
Ascii.TAB: CHARACTER = T-100B; 


7.2 Formatting 

Format: definitions 

The Format package provides procedures to format various types into strings. The 
procedures require the client to supply a string output procedure and a piece of data to be 
formatted. Where appropriate, a format specification is also required. The client may also 
specify client instance data to be used by the string output procedure. The Format package 
is a Product Common Software package. The implementation module is 
Formatlmpl.bcd. 

7.2.1 Binding 

The Format package must be bound with the String and Time packages. 


7o2o2 Specifying the destination of the output 

The editing procedures defined in Format allow a client to pass in a procedure that will be 
called once editing of the particular item has been completed This procedure will be called 
with an output string and with the clientData passed to the editing procedure. This 
procedure must be declared to be of type 

FomnatoStringProc: procedure [s: long string, clientData: long pointer*-nil]; 

Every editing procedure in Format requires a parameter of this type and clientData to be 
passed to the editing procedure. If nil is supplied for this procedure, the output is directed 
to the default output, known as a sink. The default output sink can be changed with the 
procedure 

Format.SetDefaultOutputSink: type = 

procedure [new: Format. StringProc, clientData: long pointer <-nil] 
returns [old: Format. StringProc, oldCiientData: long pointer]; 


7.2.3 String editing 

Format.Char: procedure [proc: Format.StringProc f char: character, 
clientData: long pointer*-nil]; 

Char calls on proc with a string of length 1 containing c. 

Format.LongSubStringltem: procedure [proc: Format. StringProc, ss: string. LongSubString, 
clientData: long pointer *- nil]; 
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Format.LongString, Text: procedure [proc: Format. StringProc, s: long string. 
dientData: long pointer .-nil]; 

Format. Substring: procedure [proc: Format.StringProc, ss: string.Substring, 
dientData: long pointer <-nil]; 

LongSubStringltem repeatedly calls proc with strings filled from ss. 

LongString (or Text) calls proc with string s. 

Substring calls Format. LongSubStringltem with proc and a pointer to a 
string. SubStringDescriptor whose base is ss.base, offset is ss.offset and length is 
ss.length. 

Format.Blank, Blanks: procedure [proc: Format.StringProc, n: cardinal «- 1, 
dientData: long pointer ♦—nil]; 

Format. Block: PROCEDURE [proc: Format.StringProc, block: Environment.Block, 
dientData: long pointer*-nil]; 

Format. CR: procedure [proc: Format.StringProc. dientData: long pointer*-nil]; 

Format.Line: PROCEDURE [proc: Format.StringProc, s: longstring, 
dientData: long pointer*-nil]; 

The procedure Blank(s) calls proc with a string containing n spaces. Block calls proc with 
the contents of block. CR calls proc with a string containing a carriage return. The 
procedure Line calls proc with s, then with a string containing a carriage return. 


7.2.4 Editing numbers 

The format into which numbers are to be edited is governed by a record of the form 

Format.NumberForrnat: type = record [base: [2..36]«— 10, 

zerofill: boolean «— false, unsigned: boolean*—true, columns: [0..255] «-0]; 

Format.OctalFormat: Format.NumberForrnat = [base: 8, zerofill: false, 
unsigned: true, columns: 0]; 

Format.DecimalFormat: Format.NumberForrnat * 

[base: 10,zerofill: false, unsigned: false, columns: 0]; 

The number editing procedure described below will edit the number parameter as follows: 
the number will be edited in base base in a field columns wide (zero means use as many as 
needed). If zerofill is true, the extra columns are filled with zeros, otherwise spaces are 
used. If unsigned is true, the number is treated as a cardinal. 

Two NumberFormat records are defined for convenience. OctalFormat specifies editing the 
number as a cardinal in base eight number, using as many columns as needed, no zero fill. 
DecimalFormat specifies editing the number as an integer in base ten number, using as 
many columns as needed, no zero fill. 
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Format.Nurnber: procedure [proc: Format. StringProc, n: unspecified, 
format: Format. NumberFormat,clientData: long pointer*-nil]; 

Format.LongNumber: procedure [proc: Format StringProc, n: long unspecified, 
format: Format. NumberFormat,clientData: long pointer*-nil]; 

Number and LongNumber convert n to a string of the base specified in format. If 
format.unsigned is false and n is negative, the character is output. If the numeric 
string length is less than format.columns then proc is called, perhaps multiple times, to 
output the necessary number of leading zeros (if format.zerofill) or spaces, before being 
called to output the numeric string If the numeric string length is greater than 
format.columns, then proc is called. 

Format. Decimal: procedure [proc: Format. StringProc, n: integer. 
clientData: long pointer <- nil]; 

Format.LongDecimal: procedure [proc: Format.StringProc, n: long integer. 
clientData: long pointer*-nil]; 

Decimal and LongDecimal convert n to signed base ten. proc is then called. 

Format. Octal: procedure [proc: Format.StringProc, n: unspecified, 
clientData: long pointer <- nil]; 

Format.LongOctal: procedure [proc: Format.StringProc, n: long unspecified, 
clientData: long pointer*-nil]; 

Octal and LongOctal convert n to base eight. When n is greater than 7, the character B is 
appended, proc is then called. 


7.2.5 Editing dates 

DateFormat allows the user to specify the format in which the date is to be edited by the 
procedure Format. Date. 

Format.DateForrnat: type = {dateOnly, noSeconds, dateTime, full, mailDate}; 


The different formats have the following interpretation: 
maildate: 27 Jul 83 09:23:29 PDT (Wednesday) 

full: 27-Jul-83 9:23:29 PDT 

dateTime: 27-Jul-83 9:23:29 

noSeconds: 27-Jul-83 9:23 

dateOnly: 27-Jul-83 


The maildate format is the ANSI standard format for dates. Note the leading zero on the 
time (when appropriate) and the omitted hyphens from the date. Also note that fewer time 
zones have standard abbreviations (Pacific through Eastern and Greenwich). 


Format. Date: procedure [proc: Format.StringProc, pt: Time. Packed, 

format: Format DateFormat *— noSeconds, zone: Time.TimeZone <-ANSI, clientData: 
long pointer*-nil]; 
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Date converts pt to a string of the form "27-Jul-83 9:23:29 PDT" which is truncated based 
on the specified format, proc is then called. The zone parameter indicates in which format 
numeric time zones are represented (see §7.4.2 for a description of the representations). 


7.2.6 Editing network addresses 

The following procedures can be used to edit network addresses into various forms. The 
exact form of the editing is specified with the type 

Format. NetFormat: type * {octal, hex, productSoftware}; 

octal converts the number to octal, hex, to hex, and productSoftware converts the item to 
a decimal number and then inserts a every three characters, starting from the right. 
An example of number in product software format is 4-294-967-295 

Format. HostNumber: procedure [proc: Format.StringProc, 

hostNumber: System. HostNumber, format: Format. NetFormat, 
dientData: long pointer *- nil]; 

Format. NetworkAddress: procedure [proc: Format.StringProc, 

networkAddress: System. NetworkAddress, format: Format.NetFormat, 
dientData: long pointer <- nil]; 

Format.NetworkNumber: procedure [proc: Format.StringProc, 

networkNumber: System. NetworkNumber, format: Format.NetFormat, 
dientData: long pointer*-nil]; 

Format.SocketNumber: procedure [proc: Format.StringProc, 

socketNumber: System. SocketNumber, format: Format.NetFormat, 
dientData: long pointer*-nil]; 

A network address will be edited into the form network-number # host-number # socket - 
number where the editing of the various components will be determined by format. 

7.3 Strings 

String: definitions ...; 

The String interface provides facilities for string manipulation. It is Product Common 
Software. The implementation modules for String are StringslmplA. bed and 
StringsImpIB.bcd. 

Note: The following procedures have been retained in the String interface for 
compatibility. Their use is strongly discouraged. Please see String.mesa for details of their 
definition: Stringtength, EmptyString, Equalstring, Equalstring, Equivalentstring, 
EquivalentStrings, CompareStrings, EqualSubStrings, EquivalentSubStrings. 
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7.3.1 Sub-strings 

A SubStringDescriptor describes a region within a string. The first character is 

basefoffset] and the last character is basefoffset + length-1]. 

string.SubStringOescriptor: type ■ record [base: long string, 
offset, length: cardinal]; 

strmg.SubString. long pointer to SubStringDescriptor; 

7.3.2 Overflowing string bounds 

strmg.StringBoundsFault: signal [s: long string] returns [ns: long string]; 

StringBoundsFault signal is raised when any of the append procedures described below 
would have to increase the length of their argument string’s length to be larger than its 
maxlength. The catch phrase may allocate a longer string ns and return it to 
StringBoundsFault. The operation will then be restarted as if ns had been the original 
argument. If StringBoundsFault is resumed with the value nil, the procedure that raised 
the signal will fill in the original string with as many characters as will fit. 

7.3.3 String operations 

The procedure 

stnng.WordsForString: procedure [nchars: cardinal] returns [cardinal]; 

calculates the number of words of storage needed to hold a string of length nchars. The 
value returned includes any system overhead for string storage. 

There are two case changing procedures: 

strmg.LowerCase, Uppercase: procedure [c: character] returns [character]; 

These procedures change the parameter character to lower or upper, respectively. The 
procedures are no-ops if the character is not a letter. 

string.AppendChar: procedure [s: long string, c: character]; 

AppendChar appends the character c to the end of the string s. sJength is updated; 
s.maxlength is unchanged. 

string.AppendString: procedure [to, from: long string]; 

AppendString appends the string from to the end of the string to. to.length is updated; 
to.maxlength is unchanged 

string.AppendSubString: procedure [to: long string, from: string.Substring]; 

AppendSubString appends the substring in from to the end of the string in to. to.length is 
updated; to.maxlength is unchanged. 


7-6 




Pilot Programmer’s Manual 


7 


String.Copy: PROCEDURE [to, from: LONG STRING,!; 

The procedure Copy sets the length of to to zero and then appends from to to. 
String.DeleteSubString: procedure [s: string.SubStringJ; 

DeleteSubString deletes the substring described by s from the string s.base. s.base.length 
is updated: s.base.maxlength is unchanged. 

String. Empty: PROCEDURE [s: long string,] returns [boolean]; 

The procedure Empty returns true if s is nil or if s.length is 0 and false otherwise. 

String. Equal: PROCEDURE [si, S2: LONG STRING] RETURNS [BOOLEAN]; 

Equal returns true if si and s2 contain exactly the same characters. 
string.Equivalent: procedure [si, s2: long string] returns [boolean]; 

Equivalent returns TRUE if si and s2 contain the same characters except for case shifts. 
Strings containing control characters may not be compared correctly. 

String.EqualSubString: procedure [si, s2: String.SubStringJ 
RETURNS [BOOLEAN]; 

EqualSubString is analogous to Equal. 

String.EquivalentSubString: procedure [si, s 2: string.SubString] returns [boolean]; 
Equivalentsubstring is analogous to Equivalent. 

string.Compare: procedure [si, s2: long string, ignoreCase: boolean«-true] 
returns [integer]; 

Compare lexically compares two strings and returns -1, 0, or 1 if the first is less than, 
equal to, or greater than the second. An optional parameter may be supplied to have case 
differences ignored. 

string.Length: procedure [s: long string,] returns [cardinal]; 

The procedure Length returns zero if s is nil and s.length otherwise, 
string.StringToNumber: procedure [s: long string, radix: cardinal*- 10] 

RETURNS [UNSPECIFIED]; 
string.InvalidNumber: signal; 

StringToNumber interprets the characters of s as an integer or cardinal and returns its 
value. The form of a number is: 

{spaces | controlCharacters} {'-} {baseNumber} {'B)' b| 1 Dj' d} [scaleFactor) 
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where {} indicates an optional part and "I" indicates a choice, and baseN umber and 
scaleFactor are sequences of digits. The value returned is ± baseNumber * 
radix* * scaleFactor. controlCharacters are characters whose Ascii code is less than 40B. 
The radix used depends on the contents of s and radix: if the string has a ' B or ' b, radix 
will be 8; if the string has a 'D or 'd, radix will be 10; otherwise, radix will be radix. The 
number scaleFactor is always expressed in radix 10. If s does not have a valid form or 
s.length = 0, string.InvalidNumber is raised. Values of radix other than 8 or 10, the use of 
the digits 8 and 9 when radix 8 is in effect, and the specification of a number whose value 
falls outside of the range of the target type all prod' ’ce undefined results. 

string.StringToDecimal: procedure [s: long string] returns [integer]; 

String.StringToOctal: procedure [s; long string] returns [unspecified]; 

StringToDecimal is equivalent to StringToNumberJs, 10]. StringToOctal is equivalent to 
StringToNumberfs, 8], 

string.StringToLongNumber: procedure [s: long string, radix: cardinal*- 10] 
returns [long unspecified]; 

StringToLongNumber is analogous to StringToNumber, except that returns a long 
unspecified instead of an unspecified. 

string.AppendNumber: procedure [s: long string, n, radix: cardinal <— 10]; 

AppendNumber converts the value of n to text using radix and appends it to s. radix 
should be in the interval [2..36], 

string.AppendDecimal: procedure [s: long string, n: integer]; 

AppendDecimal converts the value of n to radix 10 text and appends it to s. A leading 
minus sign will be supplied as appropriate. 

string.AppendOctal: procedure [s: long string, n: unspecified]; 

AppendOctal converts the value of n to radix 8 text and appends it to s. A "B" will be 
appended. 

string.AppendLongNumber: procedure [s: long string, n: long unspecified, 
radix: cardinal *-10]; 

AppendLongNumber is analogous to AppendNumber. 
string.AppendlongDecimal: procedure [s: long string, n: long integer]; 
AppendlongDecimal is analogous to AppendDecimal. 

7.3.3.1 String operations that perform storage allocation 

string.MakeString: procedure [z: uncounted zone, maxLength: cardinal] 

RETURNS [LONG STRING]; 


7-8 



Pilot Programmer’s Manual 


7 


The procedure MakeString returns a string large enough to contain maxLength 
characters, allocated from the zone z. 

string. MakeMDSString: procedure [z: MDSZone, maxLength: cardinal] returns [string]; 

The procedure MakeMDSString returns a string large enough to contain maxLength 
characters, allocated from the MDS zone z. 

string. FreeString: procedure [z: uncounted zone, s: long string]; 

The procedure FreeString deallocates the string s to the zone z. The string must either be 
nil or have been allocated from z. 

string.FreeMDSString: procedure [z: MDSZone, s: string]; 

The procedure FreeMDSString deallocates the string s to the MDS zone z.The string must 
either be nil or have been allocated from z. 

string.AppendCharAndGrow: procedure [to: long pointer to long string, c: character, 
z: uncounted zone]; 

The AppendCharAndGrow procedure appends the character c onto the string pointed to 
by to. Automatic expansion of the string is provided when required, that is, a new string 
will be allocated and the old will be returned to the zone z. to must point to a string 
allocated from the zone z, and the client should have no other outstanding references to 

to t. 

String.AppendExtensionlfNeeded: procedure [ 

to: long pointer to long string, extension: long string, z: uncounted zone] 
returns [boolean]; 

The AppendExtensionlfNeeded procedure checks the passed string pointed to by to to see 
if it contains an extension (contains a period followed by at least one character). If not, it 
appends extension (inserting a period if extension does not begin with a period). 
Automatic expansion of the string is provided when required, that is, a new string will be 
allocated and the old will be returned to the zone z. to must point to a string allocated from 
the zone z, and the client should have no other outstanding references to to f . 
AppendExtensionlfNeeded returns true if the extension was added and false if not. 

string.AppendStringAndGrow: procedure [to: long pointer to long string, 
from: long string, z: uncounted zone , extra: cardinal 0]; 

The AppendStringAndGrow procedure appends the string from to the string pointed to by 
to. Automatic expansion of the string is provided when required, that is, a new string will 
be allocated and the old will be returned to the zone z.. If the string must be expanded, it 
will be expanded to the new required length plus extra, to must point to a string allocated 
from the zone z, and the client should have no other outstanding references to to f . 

String. CopyToNewString: 

procedure [s: long string, z: uncounted zone , longer: CARDINAL «- 0] 
returns [newS: long string]; 
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The CopyToNewString procedure copies a string into a new string allocated from the zone 
z. The new string will be made longer characters longer than the length of s. If s is nil and 

longer is zero, newS will be nil 

String. ExpandStri ng: 

PROCEDURE [s: LONG POINTER TO LONG STRING, longer: CARDINAL , Zl UNCOUNTED ZONE]; 

The ExpandString procedure expands a string by longer characters, s must point to a 
string allocated from zone z.. 

string.Replace: 

PROCEDURE [to: LONG POINTER TO LONG STRING, from: LONG STRING, z: UNCOUNTED ZONE ]; 

The Replace procedure replaces the string pointed to by to with a copy of the string from, 
to will be automatically expanded or shortened as needed, that is, a new string will be 
allocated and the old will be returned to the zone z. If from is nil, to will be nil. to must 
point to nil or to a string allocated from the zone z, and the client should have no other 
outstanding references to to f . 


7.4 Time 


Time: definitions ...; 

The Time package provides functions to acquire and edit times into strings. The Time 
package is Product Common Software. 

The implementation module is Timelmpl. bed. 


7.4.1 Binding 

This package uses the String package and must be bound with Str ingsImplA. bed. 

7.4.2 Operations 

Time.TimeZoneStandard:TYPE a {Alto, ANSI}; 

The ANSI time zone standard labels time zones by the number of hours each zone is ahead 
of GMT. The Alto standard uses the number of hours behind GMT. For example, the 
eastern standard time zone is represented as + 5 in the Alto standard, and -5 in the *ANSI 
standard. Alto is retained for Alto-based protocol compatibility only. 

The current time and date is kept is a record of the following form: 

Time.Unpacked: type a record[ 

year: [0..2104], month: [0..12), day: [0..31], 

hour: [0..24), minute: [0..60), second: [0..60), 

weekday: [0..6], dst: boolean, zone: System.LocalTimeParameters]; 

Time. Packed: type a System. Greenwich MeanTi me; 

The fields are filled by procedures described below which operate on the time and date as 
kept internally by Pilot, year = 0 corresponds to 1968. For month, January is numbered 
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0, etc. Days of the month have their natural assignments. For weekday, Monday is 
numbered 0. zone indicates time zones. Packed is retained for Alto compatabilitv. 

Time.Current: procedure returns [time: System. GreenwichMeanTime]; 

Time.Unpack: procedure [time: System. GreenwichMeanTime «-Time.defaultTime, 
ltp:Time.LTP «-Time.useSystem] 
returns [unpacked: Time.Unpacked]; 

Time. LTP: TYPE a RECORD [ 
r: SELECT t:* FROM 
useSystem a > [], 

useThese a > (Itp: System. LocalTimeParameters] 
endcase]; 

useSystem: useSystem Time.LTP a [useSystemfl]; 
useGMT: useThese Time.LTP a [useThese[[west, 0,0,0,0]]]; 

Time.defauItTime: System.GreenwichMeanTime a System.gmtEpoch; 

Time.lnvalid: error; 

Current is equivalent to System.GetGreenwichMeanTirne, Unpack takes the Pilot-standard 
Greenwich mean time and a target time zone and computes the values for the fields in 
Unpacked. Passing defauItTime returns the current time. If Pack gets bad data, 
Time.lnvalid is raised. If the local time parameters are not available to Pilot, 
System.LocalTimeParametersUnknown is raised. 

Caution: In Utility Pilot, Systern.SetLocalTimeParameters must be called before using 

Unpack. 

The operation 

Time.Pack: procedure [unpacked: Time.Unpacked.useSysternLTP: boolean <-true] 
returns [time: System. GreenwichMeanTime]; 

converts an Unpacked into the Pilot-standard GreenwichMeanTime. If the local time 
parameters are not available to Pilot, System.LocalTimePararnetersUnknown is raised. 

The operation 

Time.Append: procedure [s: long string, unpacked: Time.Unpacked, 

zone: boolean <— false, zoneStandard: Time.TimeZoneStandard *— ANSI]; 

appends the time in human readable form to s. It adds the time zone if zone is true. 

The operation 

Time.AppendCurrent: procedure [s: long string, zone: boolean «- false. 

ltp:Time.LTP«-Time.useSystern, zoneStandard: TimeZoneStandard «- ANSI]; 

is equivalent to Time.Appendfs, Time.Unpack[Time.defauItTime, Itp], zone, zoneStandard]. 
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7.5 Memory stream 

MemoryStream: definitions. ..; 

MemoryStream is a Pilot byte stream implementation that sources or sinks its bytes from 
a client specified block of virtual memory. A primary application is to support clients of 

Courier.SerializeParameters and DeserializeParameters. 

7.LI Errors 

IndexOutOfRange: error; 

Attempting to set the position of the stream, either expicitly with MemoryStream. Setlndex, 
or implicitly with put operation, beyond the limits of the Environment.Block specified in the 
Create will cause IndexOutOfRange to be raised. 

7.1.2 Procedures 

MemoryStream. Create: PROCEDURE [b: Environment.Block] RETURNS [$H: Stream. Handle]; 

Create defines the block of virtual memory upon which subsequent stream operations 
may operate. MemoryStream makes no assertions about the content of that block of 
memory. 

The Environment.Block specified in Create limits the acceptable values for positioning 
operations as well as the amount of data that may be put to the stream (see section 1.1). 

MemoryStream. Destroy: PROCEDURE [sH: Stream. Handle]; 

Destroy deletes the state used to support the stream instance. It does not affect the content 
or existance of the block of virtual memory specified in the Create. 

Note: Destroy may also be accessed via the stream object’s delete procedure. 

MemoryStream. Setlndex: PROCEDURE [sH: Stream. Handle, position: Stream. Position]; 

Setlndex sets the position of stream for the next data operation. Attempting to set a 
position beyond the limits of the block specified in the Create will cause the error 
IndexOutOfRange to be raised (see section 1.1) 

Note: Setlndex may also be accessed via the stream object's setPosition procedure. 

MemoryStream.Getlndex: procedure [$H: stream. Handle] returns [position: stream. Position]; 

Getlndex returns the current position of the stream. The usual application for this 
information is again in conjunction with Courier.SerializeParameters and is used to find the 
length of serialized data. 

Note: Getlndex may also be accessed via the stream object's getPosition procedure. 
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This section is a general description of the organization of Pilot and its related components 
and of the various aspects of system initialization. It addresses the topics: 

• what the components of a release of Pilot are 

• the various aspects of initializing Pilot 

— these pertain to the routine operation of Pilot and client programs 
in an already established environment 

• the special considerations of initializing an environment on a new machine or disk 

• the general areas of initializing a communication network 

• the general areas of introducing a new machine into a network 

8.1 System components 

There are seven kinds of software components in a release of Pilot of interest to the client 
programmer: 

The Pilot kernel: Pilot is released as PilotKernel . bed, a file containing the object 
code of the fundamental parts of the Pilot operating system. Pilot imports the device 
faces from the heads (below) and exports most of the interfaces described in this 
manual. UtilityPilot is a variant of the Pilot kernel which is released as 
Utili tyPilotKernel . bed. It is intended to support small applications and utilities 
which must run in real memory, (see Appendix D for more details); 

The Communication package: the code allowing Pilot clients to perform inter- and 
intra-processor communication. 

The heads: for each processor, one or more files containing the object code of the 
modules which export the device faces. 

The germ: a bootstrap loader which can load a Pilot boot file into a Mesa processor and 
place it into execution. There are one or more germs for each kind of processor. 
Programmers normally have no direct contact with the germ. 

Microcode: the code which, together with the heads, implements the Mesa processor 
on a given kind of hardware. Programmers normally have no direct contact with 
microcode. 
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The optional packages: a collection of object files containing the object code of various 
packages released with and used in conjunction with Pilot. 

Development tools: a collection of Pilot boot files and object files which provide support 
for developing Pilot-based software. Among these are CoPilot, the debugger; Tajo, an 
executive and environment for general purpose programming; and Othello, the Pilot 
disk and volume utility. 

The documentation accompanying a Pilot release describes in detail the file names of the 
available components, the functions they implement, and the interfaces they export. 
Please refer to that documentation for details. 

Caution: There may be a number of interfaces which are exported by the Pilot 
components, but are not documented in this manual. They exist for the convenience of the 
implementation and for special purposes outside the scope of this document. 
Unauthorized use of these interfaces is not supported and is strongly discouraged. They are 
subject to change without general notice or review, and projects which use them 
improperly are subject to considerable risk from one release of Pilot to the next. 

8*2 Pilot initialization 

The primary method of preparing a Pilot client system for operation is to bind it with 
PilotKernel.bcd, the appropriate heads, and the desired optional packages into a single 
object file representing the whole system. This object file is then processed by a program 
called MakeBoot, described in the Mesa User's Guide , to create a boot file. The boot file 
may be installed on a rigid disk, floppy disk, or Ethernet server for loading in response to 
some hardware operation, or it may be invoked by software using the facilities of the 
TemporaryBooting interface. If the boot file is invoked by software, it is possible for the 
invoking program to pass a limited form of parameters called switches for interpretation 
by the booted system. 

An alternative method of invoking a program is to boot a system and cause that to load the 
object file of the desired program, using the facilities in the Runtime interface, which are 
implemented by RuntimeLoader.bcd. This is especially appropriate if the same boot file 
can load a lot of different programs or if the programs being loaded are under development 
and constantly evolving. For example, the Mesa development environment, provides 
facilities for the user to dynamically load programs. 

When a boot file is invoked, the state of the processor is reset. The part of the boot file 
representing initially resident code and data is copied into memory and the virtual 
memory mapping hardware is set accordingly. The configuration of I/O devices and of real 
memory must be determined and tables established accordingly. The heads must be 
initialized to reset the I/O devices. Then Pilot begins to execute. It opens the system 
physical and logical volumes, creates or finds certain files for its own use, creates and 
maps spaces for code and data, scavenges volumes if necessary, and performs other 
necessary initialization functions. Initialization of Pilot on a new or recently erased 
volume typically takes a bit longer than initialization of an established volume where the 
various files and control information already exist. 

Pilot (i.e., PilotKernel.bcd) initializes disks containing Pilot volumes as follows: the 
system volume is the logical volume on which the boot file resides. The physical volume 
containing the system volume is automatically brought on-line and the system logical 
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volume is opened. Clients may bring other physical volumes on-line and open the logical 
volumes contained on them, and they may take existing physical volumes offline after 
first closing all of the contained logical volumes. (It is not meaningful to close the system 
volume, as Pilot uses this for its own operation.) 

UtilityPilot, on the other hand, assumes that there is no system volume, and no volumes 
are brought on-line at initialization time. This is necessary so that a client can initialize a 
new disk to be a physical volume without first depending upon it. Once a disk is formatted 
to be a physical volume, it may be brought on-line in the usual way. Initialization of 
volumes is described in the next section. 

Finally, after initialization is complete, Pilot starts the client by calling the procedure Run 
from the interface PilotClient. This is the only procedure imported by Pilot from the client 
system. 

It is intended to eventually provide a facility whereby the state of a running system can be 
captured in a boot file for later or repeated restart. This facility will be useful for reducing 
the initialization time of both Pilot and client once the operating environment is 
established. The normal mode of operation will be for a boot file created by MakeBoot to 
initialize the Pilot and client environment, to create files and gather information as 
necessary, then to take a snapshot of this state on a second boot file. The second boot file 
would be the one installed for normal booting when the system element is turned on or 
restarted. There are a number of constraints in this mode of operation, not all of which are 
fully understood at this time. Among them are: 

The boot file created this way is valid only on the system element on which it is 
created and only while the hardware configuration remains the same. It will be 
invalidated if the amount of memory changes, the processor ID (i.e., the electronic 
serial number from which all Universal ID's are made) is changed as a result of 
repairs, if critical devices are removed, etc.; 

Files which are known or mapped at the time the boot file was created must not be 
deleted subsequently; 

There should be no outstanding activity on any of the devices; 

There should be no outstanding connections or activity in the communication network 
at the time this special boot file is created. 

Thus, such a boot file is specific to the machine and circumstances in which it is created. It 
is therefore called a local boot file. By contrast, a boot file created by MakeBoot may be 
transported to any machine (of the right configuration) and executed there. Such files are 
called universal boot files. 


8.3 Volume initialization 

FormatPilotDisk: definitions ...; 
OthelloOps: definitions 


8-3 




8 


System Generation and Initialization 


There are several steps in initializing a disk for use as a Pilot volume: 


The disk must be formatted into sectors corresponding to Pilot pages with appropriate 
headers, labels, and data blocks; 

The disk must be scanned, any unusable pages must be recorded, and a physical 
volume must be created; 

One or more logical volumes must be created on the physical volume; 


Various microcode, germ, and boot files must be copied onto the logical volumes and, 
pointers must be set to indicate that these files be invoked when the machine is 
booted. 


In the development environment, formatting is normally done by EIDisk (the disk 
diagnostic): all other initialization is done by Othello, the disk utility. Product application 
have their own UtilityPilot-based disk initialization utilities. Applications may also 
provide facilities in their Pilot-based systems for initializing, for example, removable 
volumes as part of routine operation. 

An important part of formatting a disk is to scan the disk for unusable pages (the format 
package provides a scanning procedure) and to mark them as bad. Pilot will avoid placing 
any data or control information on such bad pages for the life of the physical volume. A 
page of a physical volume may be marked bad at a later time, but this will cause the 
information on that page to be lost. (The facilities of the Scavenger interface (see §4.4) can 
be used to recover some of the lost information.) Note that a characteristic of rigid disks is 
that a disk is expected to have some unusable pages at the time of manufacture, but that 
the rate of pages going bad during operation over the life of the disk is expected tor be 
infinitesimal. 

The Volume interface provides facilities for creating logical volumes on a physical volume. 
A logical volume has a volume type indicating its intended use to contain normal Pilot 
clients, the debugger, the debugger’s debugger, or for non-Pilot purposes. Logical volumes 
of different types are kept separate by Pilot so that a system will not affect its debugger. 
Once a logical volume has been created, it may be opened and files copied onto it. 

Finally, a disk may need to be prepared for booting. There are typically four kinds of files 
that need to be fetched to the disk: the initial microcode, the Pilot microcode, the germ, 
and the boot file. The initial microcode is microcode that typically lives in a special place 
on the disk (outside any logical volume) and is invoked by the hardware booting logic of 
the machine. It is the program that reads the Pilot microcode and the germ from the disk. 
The Pilot microcode is the main microcode for the operation of the machine, and lives in a 
file on a logical volume, along with the germ and boot file. A formatting package provides 
the facility for installing the initial microcode (since its location is specific to the type of 
device), and the interface OthelloOps provides facilities for installing and setting pointers to 
the microcode, germ, and boot files. These pointers are necessary so that the initial 
microcode can find the Pilot microcode and germ, and so that the germ can find the Pilot 
boot file. 


8-4 





Pilot Programmer’s Manual 


8 


This section describes those interfaces and object files distributed with Pilot that allow 
clients to create their own volume initializers. OthelloOpsImpl .bed implements the 
OthelloOps operations, and FormatPilotDisklmpl . bed implements the FormatPilotDisk 
operations. Both packages are clients of Pilot and UtilityPilot. 

8.3.1 Formatting physical volumes 

Before a physical volume can be presented to the CreatePhysicalVolume operation for the 
first time, it must be formatted into sectors corresponding to Pilot pages with appropriate 
headers, labels and data blocks. As a side effect, formatting finds many of the bad pages 
on the disk so that they can be marked as bad after a Pilot physical volume has been 
created. 

Pilot disk families are formatted using the following operation 

FormatPilotDisk. RetryLimit: type ■ [0..254); 

FormatPilotDisk. noRetries: FormatPilotDisk. RetryLimit = 0; 

FormatPilotDisk. retryLimit: FormatPilotDisk. RetryLimit = last[ FormatPilotDisk. RetryLimit]; 

FormatPilotDisk.Forrnat; PROCEDURE [h: Physicaivoiume. Handle, 

firstPage: FormatPilotDisk. DiskPageNumber, count: long cardinal, 
passes: cardinal 10, retries: FormatPilotDisk. RetryLimit <- noRetries]; 

FormatPilotDisk.ForrnatBootMicrocodeArea: procedure [h: Physicaivoiume. Handle, 
passes: cardinal, retries: FormatPilotDisk. Retry Limit]; 

FormatPilotDisk. DiskPageNumber: type ■ Physicaivoiume. PageNumber; 

FormatPilotDisk. NotAPilOtDisk: ERROR; 

FormatPilotDisk.FormattingMustBeTrackAligned: error; 

FormatPilotDisk. BadPage: signal [p: FormatPilotDisk. DiskPageNumber]; 

Format formats count pages of the disk h starting at page firstPage. If a problem occurs 
when verifying headers, labels, or data, retries is the number of times to retry the format 
operation on that page. Passes is the number of times to go over the disk for bad pages.If 
any are found, BadPage will be raised. If h does not denote a Pilot disk drive, 
NotAPilotDisk will be raised. If h denotes a drive of the SA1000 family or Quantum 
family, the run of pages to be formatted must start at the beginning of a track and end on 
the last page of a track or FormattingMustBeTrackAligned will be raised. 
Physicaivoiume. ErrorfalreadyAsserted] will be raised if the volume is online (i.e., asserted to 
be a Pilot volume). 

FormatBootMicrocodeArea formats the area of the disk on h where microcode will reside. 
If Pilot is unable to install microcode on the disk drive denoted by h, 
CantfnstallUCodeOnThisDevice is raised. See the previous paragraph for description of 
other parameters and errors raised. 
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FormatPilotDisk. D is klnfo: PROCEDURE [h: PhysicalVolume.Handle] RETURNS [ 

firstPilotPage: FormatPilotDisk.DiskPageNumber, countPages: PhysicalVolume. PageCount, 
pagesPerTrack: cardinal, pagesPerCylinder: cardinal]; 

If h does not denote a Pilot Disk drive, the error FormatPilotDisk. NotAPilotDisk is raised. 
firstPiiotpage is the first page on the device where Pilot volumes may begin. countPages is 
the total number of pages on that volume. 

Note: For clients who use the FormatPllotDisk interface to install microcode, NotAPilotDisk is 
now raised by any procedures that previously raised 

FormatPiiotDisk.CantlnstallUCodeOnThisDevice. 

8.3.2 Checking drives for bad pages 

The following procedure permits scanning an already-formatted disk to determine if there 
are any bad pages on the disk. The client may then inform Pilot of these bad pages, via 
PhysicalVolume.MarkPageBad, so that Pilot will no longer reference them. 

FormatPilotDisk .Scan: PROCEDURE [h: PhysicalVolume. Handle, 

firstPage: FormatPilotDisk.DiskPageNumber, count: long cardinal, 
retries: FormatPilotDisk.RetryLimit 10]; 

Scan scans the indicated section of the disk for bad pages, retries number of times per each 
bad page, and then reports them by raising the signal BadPage. The signal may be 
resumed to continue the scan. If h does not denote a Pilot disk drive, the error 
NotAPilotDisk will be raised. PhysicalVolume. Error[alreadyAsserted] will be raised if the 
volume is online. 

8.3.3 Microcode and boot files 

This section discusses boot files, which contain ready-to-run Pilot-based systems that can 
be loaded by a germ for execution, and microcode files, which contain the Mesa emulator 
for a given machine. Both boot files and microcode files must be installed , i.e., made 
known to Pilot, the germ and microcode. The FormatPilotDisk and OtheiioOps interfaces 
provide facilities for dealing with boot files and microcode. The TemporaryBooting interface 
provides the means of actually invoking a boot file. 

Note: Installing germ and microcode files on an SA800 disk is not directly supported by 
the current version of Pilot. They may be installed using the utility program 
MakeDLionBootFloppyTool (see Mesa User's Guide for details). 

The lowest level of microcode is the initial microcode, the microcode that is read by the 
hardware booting logic of the system element. It is installed by the operation 

FormatPilotDisk.lnstallBootMicroCOde: PROCEDURE [h: PhysicalVolume. Handle, 
getPage: procedure returns[long pointer]]; 

FormatPilotDisk. MicrocodelnstallFailure: signal [m: FormatPilotDisk. FailureType]; 

FormatPilotDisk. FailureType: type = {emptyFile, firstPageBad, flakeyPageFound, 
microcodeTooBig, other}; 
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The microcode is installed on the disk h. This operation finds sequential pages of the 
microcode file by repeatedly invoking getPage. The end of the microcode file is indicated 
when getPage returns nil. The pointer returned by getPage must denote a resident page. 
If an error is found in the microcode file, FormatPilotDisk.MicrocodelnstallFailure is raised 
and the attempt to install the microcode has failed (any previous microcode is destroyed 
unless emptyFile is the error). If FormatPilotDisk.MicrocodelnstallFailure is resumed, 
getPage will be called until nil is returned but the data will be ignored. emptyFile 
indicates that the microcode file was empty, i.e., getPage returned nil the first time that it 
was called. If the first page of the microcode is bad, firstPageBad is raised. If some page of 
the disk reserved for the boot microcode is found to be unusable, flakeyPageFound is 
raised, indicating a problem with the disk. If an attempt is made to install too large a 
microcode file, microcodeTooBig will be raised. The error other is raised if the 
installation failed in some other way. If h does not denote a pilot disk drive, the error 
FormatPilotDisk.NotAPilotDisk will be raised. If Pilot is unable to install microcode on the 
disk drive denoted by h, FormatPilotDisk.CantlnstallUCodeOnThisDevice is raised. 

There are four types of boot files; clients may have as many of each as they desire. 

OtheiioOps.BootFileType: type * {hardMicrocode, softMicrocode, germ, pilot, 
pilotSnapshot}; 

A softMicrocode boot file contains Pilot microcode; it is typically loaded by the initial 
microcode and contains the Mesa emulation microcode. A germ boot file contains a germ, 
which is a bootstrap loader used to load a Pilot boot file and start it executing. Both pilot 
and pilotSnapshot boot files contain the image of a Pilot suitable for loading by a germ 
into a processor for execution. A pilot boot file is produced by MakeBoot and a 
pilotSnapshot boot file is produced by special facilities. hardMicrocode boot files are not 
currently used. 

Before a Pilot file may be installed as a boot file, it must be made bootable by invoking 

otheiioOps. Make Bootable: procedure [file: File.File, 

type: OtheiioOps.BootFileType, firstPage: Fiie.PageNumber]; 

otheiioOps.InvalidVersion: error; 

This operation modifies file so that it is readable by the boot loader or microcode (the 
operation does not change the contents of the file, it only modifies the file labels), file must 
be writable and permanent and the logical volume that contains it must be open. If file is 
unknown to Pilot, either File. Unknown or Volume. Unknown will be raised. If the specified 
boot file is not compatible with the version of Pilot doing the MakeBootable, 
InvalidVersion will be raised. In this case, the file is still made bootable so as to permit 
installation of boot files with incompatible version numbers. MakeBootable may also 
raise Volume. NotOpen and Volume. NotOnline . 

Before changing the size of a file that has been made bootable, the following operation 
should be invoked 

otheiloOps.MakeUnbootable: procedure [file: File.File, 

type: OtheiioOps.BootFileType,firstPage: Fiie.PageNumber]; 
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The same restrictions as for MakeBootable apply, file may be deleted without invoking 

MakeUnbootable first. 

Associated with every logical and physical volume is a default boot file of each type. These 
may be set and retrieved by invoking the operations 

othelloOps.SetPhysicalVolumeBootFile: procedure [file: File.File, 
type: OthelloOps.BootFileType, firstPage: File.PageNumber]; 

othefioOps.SetVolumeBootFile: procedure [file: File.File, 

type: OthelloOps.BootFileType, firstPage: File.PageNumber]; 

The logical volume containing file must be open. If file is unknown to Pilot, either 
File. Unknown or Volume. Unknown will be raised. The information set by these operations 
may be retrieved by invoking 

otheiloOps.GetVolumeBootFile: procedure [IvID: volume. ID, 
type: OthelloOps.BootFileType] 
returns [file: File.File, firstPage: File.PageNumber]; 

otheiloOps.GetPhysicalVolumeBootFile: procedure [pvID: Physicaivolume.lD, 
type: OthelloOps.BootFileType] 
returns [file: File.File, firstPage: File.PageNumber]; 

Logical volume IvID must be on-line, i.e., contained on a physical volume that is known to 
Pilot. If the physical volume is only partially online, Volume.NotOnline will be raised. If 
the IvID is not open, Volume.NotOpen will be raised. Volume.NeedsScavenging and 
Volume.ReadOnly may also be raised. If IvID is unknown to Pilot, Volume.Unknown is 
raised. If pvID is unknown to Pilot, PhysicalVo(ume.Error[physicalVolumeUnknown] is 
raised. 

Pilot can be told to forget that a logical or physical volume has a default boot file of some 
type by invoking 

OthelloOps.VoidVolumeBootFile: procedure [IvID: Volume.lD, 
type: othelloOps. BootF i I eType]; 

OthelloOps.VoidPhysicalVolumeBootFile: PROCEDURE [pvID: Physicaivolume.lD, 
type: OthelloOps.BootFileType]; 

Logical volume IvID must be open or Volume.Unknown will be raised. Physical volume 
pvID must be on-line or PhysicalVolume.Error[physicafVolumeUnknown] will be raised. 

Every boot file of type pilot can have an explicit pointer to a debugger for that boot file, 
i.e., a debugger that will be invoked whenever that boot file is loaded and calls a debugger. 
Normally, Pilot finds a debugger on a volume of the next higher type than the volume 
being booted. This is not sufficient if the debugger needs to be called very early in Pilot 
initialization, or if the boot file is built on top of UtilityPilot, which never looks for a 
debugger. 

otheiioOps.SetDebugger: procedure [debuggeeFile: File.File, 
debuggeeFirstPage: File.PageNumber, debugger: Volume.lD, 
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debuggerType: Device. Type, debuggerOrdinal: cardinal] 
returns [OtheiioOps.SetDebuggerSuccess]; 

OtheiloOps.SetDebuggerSuccess: type s {success, nullBootFile, noDebugger, 
cantWriteBootFile, notlnitialBootFile, cantFindStartListHeader, 
startListHeaderHasBadVersion, other}; 

The file debuggeeFile must permit writing and denote a file on a volume that is open. The 
first page of the boot file within the file debuggeeFile is denoted by debuggeeFirstPage 
(normally this is zero). The debugger will be found on the device denoted by 
debuggerType and debuggerOrdinal. The debugger is on volume debugger of the 
physical volume contained on that device. The returned value success indicates that the 
pointers were set. 

If nullBootFile is returned, debuggeeFile is either unknown or the volume it resides on is 
unknown, not online or not open. If no installed debugger can be found on debugger, 
noDebugger is returned. If Pilot is unable to modify the boot file denoted by 
debuggeeFile, cantWriteBootFile is returned. The boot file denoted by debuggeeFile must 
not be a restart file since they can not have their debugger pointers set. If it is, 
notlnitialBootFile is returned. A return of cantFindStartListHeader indicates that the boot 
file header has probably been damaged, or that the boot file has been shortened. If the 
specified boot file was created by an earlier version of either Pilot or MakeBoot, Pilot is 
unable to access it and startListHeaderHasBadVersion is returned- If Pilot is unable to set 
the debugger pointers for some other reason (i.e., the boot file is too short, missing pages 
exist, or the bootfile is of the wrong version), this operation will return other. If debugger 
is unknown to Pilot, Volume. Unknown will be raised. 

8.3.4 Miscellaneous operations 

A Pilot physical volume consists of the pieces of one or more logical volumes. Each such 
piece is known as a subvolume. The subvolumes on a physical volume can be enumerated 
by invoking 

OthelloOps.GetNextSubVolume: PROCEDURE [pvID: PhysicalVolume.lD, • 
thisSv: othelloOps.SubVolume] 
returns [nextSV: OthelloOps.SubVolume]; 

OthelloOps.SubVolume: type = record [IvID: volume. ID, 
subVolumeSize: volume.PageCount, 

firstLVPageNumber: otheiioOps.LogicalVolumePageNumber, 
firstPVPageNumber: Physicaivolume.PageNumber]; 

otheiioops.LogicalVolumePageNumber: type * long cardinal; 

OthelloOps.nullSubVolume: OthelloOps.SubVolume * [volume.nulllD, 0,0,0]; 

QthelloOps.SubVolumeUnknown: error [sv: OthelloOps.SubVolume]; 

This operation is a stateless enumerator and begins and ends with nullSubVolume is the 
argument and ends when nullSubVolume is the result. If thisSv can not be found on pvID, 
SubVolumeUnknown is raised. A SubVolume identifies a logical volume, IvID. The 
number of pages that this piece of that logical volume contains is given by subVolumeSize. 


8-9 




8 


System Generation and Initialization 


The subvolume begins at page number firstLVPageNumber within IvID, and at page 
number firstPVPageNumber within pvID. If pvID is unknown to Pilot, 
Physicalvolume.Error[physicalVolumeUnknown] is raised. 

Note: This operation is designed to deal with logical volumes that span multiple physical 
volumes. Since the current version of Pilot does not provide the facility to create such 
logical volumes, firstLVPageNumber is always 0, and subVolumeSize always gives the 
actual size of IvID. 

Pilot reserves the right to delete some or all temporary files on a logical volume when that 
volume is opened for writing. The following operation is guaranteed to delete all 
temporary files on a logical volume. 

otheiioOps.DeleteTempFiles: procedure [volume. ID]; 
otheiioOps.VolumeNotClosed: error; 

The specified volume must be closed or VolumeNotClosed will be raised. Volume.Unknown, 
Volume.Readonly, Volume.NotOnline, volume.NeedsScavenging may be raised by this 
procedure. 

The number of pages available on a storage device on a given drive holds is given by 

othelloOps.GetDriveSize: procedure [h: Physicaivolume. Handle] 
returns [nPages: long cardinal]; 

The following operation converts a character string denoting which switches should be 
down when booting a boot file into a System. Switches. 

otheiioOps.DecodeSwitches: procedure [switchstring: long string] 
returns [switches: System. Switches]; 

othelloOps.BadSwitches: error; 

The semantics of the switch string passed to DecodeSwitches as follows: the characters 
and mean set the next specified switch to System. UpDown[up]; a phrase of the form 
"\xxx", exactly three in length, is interpreted as the octal value of the switch that is to be 
set. Note that the order of switches is significant in that only the last (rightmost) setting 
(or clearing) of a particular switch is retained. Thus, the switches "ab~~a", "ab-a” and "b" 
are all equivalent. If a character is not a valid switch name, BadSwitches is raised. 

It is possible to set default switches in boot files and to associate an expiration date with a 
boot file: 

otheiioOps.SetGetSwitchesSuccess: type = otheiioOps.SetDebuggerSuccess[success..other]; 

otheiioOps.GetExpirationDateSuccess: type ■ 

OthelioOps.SetDebuggerSuccessfsuccess.. other]; 

othelioOps.SetExpirationDateSuccess: type = 
otheiioOps.SetDebuggerSuccess[success..other]; 
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otheiioOps.GetExpirationDate: procedure [file: File.File,firstPage: File.PageNumber] 
returns [othelloOps.GetExpirationDateSuccess, System. GreenwichMeanTime]; 

OthelloOps.SetExpirationDate: procedure [file: File.File, firstPage: File.PageNumber 
* expirationDate: System.GreenwichMeanTime] 
returns [otheiioOps.SetExpirationDateSuccess]; 

otheiioOps.GetSwitches: procedure [file: File.File,firstPage: File.PageNumber] 
returns [othelloOps.SetGetSwitchesSuccess, System. Switches]; 

otheiioOps.SetSwitches: procedure [file: File. File, 

firstPage: File.PageNumber, switches: System. Switches] 
returns [otheiioOps.SetGetSwitchesSuccess]; 

The expiration date is used as a validity check on the processor clock. When a boot file is 
booted, Pilot attempts to ensure that the processor clock is set correctly. If the processor 
clock can not be set from the Ethernet, or is not set to a time less than or equal to the boot 
file's expiration date, Pilot will refuse to boot and will hang with an appropriate 
maintenance panel code. The logical volume on which the boot file resides must have been 
opened in order to invoke these procedures. 

Note: These comments only apply to Pilot. For UtilityPilot, the client is always 
responsible for ensuring that the processor clock is set correctly. 

Each boot file may also contain default boot switches. These are set and retrieved by 
SetSwitches and GetSwitches. When a boot file is booted, Pilot will set the system 
switches to the value passed to it by the client booting program if they are not equal to 
System. defaultSwitches; otherwise, it sets them to the boot file's default switches. 

To aid the client in setting the processor clock to a valid value: 

OthelloOps.lsTimeValid: PROCEDURE RETURNS [valid: boolean]; 

othelioOps.SetProcessorTime: procedure [time: System. GreenwichMeanTime]; 

othelloOps.GetTimeFromTimeServer: procedure returns [serverTime: 

System. GreenwichMeanTime, serverLTPs: System. LocalTimeParameters]; 

otheiioOps.TimeServerError: error [error: othelloOps.TimeServerErrorType]; 

othelloOps.TimeServerErrorType: type ■ {noCommunicationFacilities, noResponse}; 

The validity of the time in the processor clock can be ascertained by calling IsTimeValid. 
The processor clock can be explicitly set by calling SetProcessorTime. This is required of 
all UtilityPilot clients as their first action upon gaining control. The time servers on the 
network can be queried for their notion of the current time by calling 
GetTimeFromTimeServer which returns the time that the time servers believe it is, as well 
as the local time parameters that they are using. The error TimeServerError indicates that 
the attempt to access a time server failed; noCommunicationFacilities indicates the 
processor is not connected to the Ethernet; noResponse indicates that there was no 
response from any time server on the local network. 
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8*4 Communication initialization 

Local networks are interconnected logically via machines executing an internetwork 
routing function. Physically, the interconnection of networks can be via a phone line link 
or via a processor with multiple ethernet boards. All Pilot processors contain a simple 
routing function, which is capable of requesting routing information from internetwork 
routers. 

All machines running Pilot are automatically initialized to do routing. They discover 
their local network number(s) by broadcasting for routing information at initialization 
time or via routing update packets that are broadcast by internetwork routers. 

There is a local network, thus network number, for every ethernet board in a Pilot 
processor. The network number is assigned via an administrative method that assigns 
unique 32-bit numbers. 

When a Pilot processor is restarted, it does not know its network number. Until it is 
otherwise notified of a new number, it uses a default number, referred to as the unknown 
network number. A local network can operate correctly without an internetwork router; 
all the machines on the network use the same constant, unknown network number. If all 
machines on a network use the unknown network number in their network addresses, 
completely general communication is possible. If the default network number is used, 
there is no special communication initialization necessary to assign or discover the local 
network number. 


8.5 Booting 


TemporaryBooting: definitions 

Pilot supports installing boot files on logical volumes, and booting from a specified file or 
logical volume. The operations providing this support are in the interface TemporaryBooting, 
the name of which reflects the fact that it is expected that these facilities will evolve 
somewhat before the final interface is frozen. Comments would be appreciated on this 
interface to help shape the final one. 

A boot file is a client-on-Pilot configuration which has been converted by MakeBoot into a 
ready-to-run form. It is executed by loading it into a suitable processor with the Pilot boot 
loader, which is known as the germ. The boot file commences execution by first 
initializing Pilot and then invoking PilotClient.Ruri. Pilot associates a boot file with each 
logical, and with each physical, volume so that booting from that volume means loading 
the associated boot file. It is recommended that the boot file for a physical volume be the 
boot file for some logical volume on that physical volume, though this is not required. 
Pilot also provides an operation for booting directly from a file, which need not be the 
installed boot file of its volume. 

Setting up a bootable file involves several steps. A file of the right size must be created, 
and its contents must be written with the boot file as produced by MakeBoot. Once the file 
is created, the operation MakeBootable must be applied to the file, modifying it in such a 
way that the germ can read it. Then the file may be booted using the operation 
BootFromFile. For this operation, installing the file is not necessary. If it is desired to 
associate this file with a particular logical volume, the file must be installed using the 
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operation InstallVolumeBootFile. A subsequent BootFromVolume operation applied to 
that volume (e.g., by Othello, or by a client program analogous to Othello) will cause the 
installed system to run. Similarly, for a physical volume, use 

InstallPhysicalVolumeBootFile to install a boot file, followed by a call on 
BootFromPhysicalVolume or BootButton, or by pushing the boot button. 

8.5.1 Creating a boot file 

A boot file is created in the normal fashion, using File.Create. The operations in 
TemporaryBooting are set up in such a way that a boot file may begin with a client-provided 
leader of one or more pages: in the relevant operations, a firstPage parameter specifies the 
page at which the "real M boot file (as output by MakeBoot) begins. 

A boot file may have any file type. The interface item TemporaryBooting.tBootFile remains 
for compatibility (with a value of FileTypes.tUntypedFile). It will disappear in a later 
release. 

As is always the case when creating a Pilot file, it is better to specify the actual size (i.e., 
the number of data pages output by MakeBoot, plus the number of leader pages to be 
prefixed) when creating it, rather than doing a series of File.SetSize operations. This gives 
Pilot the best opportunity to allocate the file in a small number of contiguous portions, 
which reduces both access times and storage overhead in Pilot’s data structures. (See also 
the discussion under "Updating a boot file" below.) 

8.5.2 Writing the contents of a boot file 

The Space operations Map, Unmap, Copyln, and CopyOut apply to bootable files just as to 
any other, allowing the contents to be written. Since a boot file is originally built by 
MakeBoot, which runs in a different environment, part of the process of installing a boot 
file is to copy it into the previously created Pilot boot file. This is typically accomplished 
via the Ethernet, e.g., Othello's fetch command. 

8.5.3 Making a boot file bootable 

Once a boot file has been created and written with the appropriate contents, it must be 
subjected to the operation 

TemporaryBooting. MakeBootable: procedure [file: File.File, 
firstPage: File.PageNumber 4-0]; 

The parameter firstPage specifies the first page containing the information produced by 
MakeBoot, e.g., the page following the client leader pages, or zero if no leader pages are 
present. 

If the file doesn't contain a valid Pilot boot file starting at firstPage, the following error is 
raised: 

TemporaryBooting.InvalidParameters: error; 
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If the file being made bootable has an invalid version, the following error is raised: 

TemporaryBooting.InvalidVersion: error; 

The file is made bootable before this error is raised so that boot files that are incompatible 
with Pilot 11.0 can be installed by Pilot 11.0. 

8.5«4 Installing a boot file 

To establish a file as the boot file of a particular logical volume, use the operation 

Temporary Booting. Instal I VolumeBootFile: procedure [file: File.File, 
firstPage: File.PageNumber <-0]; 

The file should already have been made bootable. The parameter firstPage has the same 
significance as for MakeBootable. Note that InstallVolumeBootFile does not take an 
explicit volume parameter because a boot file may only be installed on the volume 
containing that file. 

To associate a file as the boot file of a particular physical volume, use the operation 

TemporaryBooting.lnstallPhysicalVolumeBootFile: procedure [file: File.File, 
firstPage: File.PageNumber <-0]; 

8.5.5 Booting a boot file 

Four operations are provided: booting a specified boot file, booting from the file installed 
on a specified logical volume, booting from the file installed on a specified physical 
volume, and simulation of the boot button. A program may boot from any Pilot-formatted 
volume, regardless of its type. These operations do not return. Control passes irrevocably 
to the new boot file. 

TemporaryBooting.BoOtFromFile: PROCEDURE [file: File.File, 
firstPage: File.PageNumber *~0, 
switches: System.Switches *-System.defaultSwitches]; 

Note: Pilot 11.0 will not successfully complete the TemporaryBooting.BoOtFromFile 
operation if the file is temporary and firstPage is zero. 

TernporaryBooting.BOOtFromVolume: PROCEDURE [volume: Volume.ID, 
switches: System. Switches System. defaultSwitches]; 

TernporaryBooting.BOOtFromPhysicalVolume: PROCEDURE [volume: Volume.ID, 
switches: System. Switches System. defaultSwitches]; 

Note that the parameter to BootFromPhysicalVolume is not a physical volume identifier, 
but the identifier of any logical volume on that physical volume. 

TemporaryBooting.BootButtOn: PROCEDURE [ 

switches: System.Switches System.defaultSwitches]; 
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The value of the defaultSwitches parameter represents all switches as being up. Errors 
resulting in improper arguments to these booting operations typically result in a 
maintenance panel code and a crash. 

8.5.6 Updating a boot file 

From time to time it is necessary to install a new version of a boot file onto a volume. 
Several approaches are possible: 

1. a new file can be created, written, made bootable, and installed; then the old boot file 
may be deleted. 

2. an existing boot file may be overwritten with new contents; then MakeBootable must 
be applied again. InstallVolumeBootFile need not be reapplied. 

The first approach has the advantage that it never leaves the volume in an inconsistent 
state. It has the disadvantage of requiring extra disk space during the time the old and 
new boot files exist. If the second approach is used, then before rewriting the old boot file’s 
contents, it must be made unbootable using the operation 

TemporaryBooting.MakeUnbOOtable: PROCEDURE [file: File.File, 

firstPage: Fiie.PageNumber«-0]; 

To understand the purpose of this operation, a little background is helpful. MakeBootable 
writes an absolute disk address (called a link) in otherwise unused words of the label of 
some boot file pages. The germ uses this information rather than the ordinary Pilot 
volume file map structure to read the file. If the size of the boot file changes when it is 
being updated, new physical disk pages may be allocated, invalidating some of the old 
links. Thus Makellnbootable is provided to remove the old links from a boot file about to 
be updated. Afterward, MakeBootable must be used to put in the correct new links. 

8.5.7 Atomic saving and restoring of Pilot instances 

TemporaryBooting.BoOtLocation: TYPE a RECORD [ 
body: select bootLocation:* from 
bootButton, none ■ > null, 

physicalVolume * > [pvLocation: TemporaryBooting.PVLocation], 
logicalVolume ■ > [volumeLocation: TemporaryBootlng.VolumeLocation], 
file a > [fileLocation: TemporaryBooting.FileLocation], 
endcase]; 

TemporaryBooting.PVLocafion: TYPE [11]; 

TemporaryBooting.VolumeLocation: TYPE [11]; 

TemporaryBooting.FileLocation: TYPE [11]; 

A BootLocation describes a place that the state of a running Pilot may be saved in or 
restored from. A bootButton BootLocation and a none BootLocation are always valid; 
the other variants are only valid for limited periods of time as described below. The 
conservative approach is never to store these other variants in a permanent location but to 
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recreate them just before using them (as parameters to Outloadinload). Currently, it is 
only possible to save state in a file BootLocation. 

The following procedures return a BootLocation for the specified location. For each 
operation, the circumstances under which the returned information becomes invalid are 
noted. 

TemporaryBooting.GetFileLocation: PROCEDURE [file: Fiie.FNe,firstPage: Fiie.PageN.umber0] 
RETURNS [boOtLOCation: file TemporaryBooting.BOOtLocation]; 

The returned BootLocation is valid so long as the specified file is neither deleted nor has 
any of its attributes changed (including size and permanency). Scavenging may 
invalidate the returned BootLocation if the file was damaged and the client scavenger 
repaired the damage. The returned BootLocation is also only valid if the specified file has 
been made bootable (via TemporaryBooting.MakeBootable) and is not subsequently made 
unbootable. GetFileLocation raises TemporaryBooting.InvalidParameters if the specified file 
page is beyond the end of the file. It may also raise File.MissingPages, File.Unknown, 
Volume.NotOnline, Volume.NotOpen, Volume.Unknown. 

TemporaryBooting.GetVolumeLocation: PROCEDURE [volume: Volume.lD] 

RETURNS [bootLOcation: logicalVolume TemporaryBooting.BOOtLocation]; 

The returned BootLocation refers to the boot file installed on the logical volume. It is 
valid as long as the boot file on the specified volume is not deleted. The comments for the 
validity of returned BootLocations in GetFileLocation also apply here. 

TemporaryBooting.InvalidPararneters will be raised if the specified volume does not have a 
Pilot boot file installed on it. volume.Unknown, Volume.NeedsScavenging, and 
Volume.NotOnline may also be raised. 

TemporaryBooting.GetPVLocation: PROCEDURE [volume: PhysicalVolume.lD] 

RETURNS [bootLOcation: physicalVolume TemporaryBooting.BOOtLocation]; 

The returned BootLocation refers to the boot file installed on the physical volume. It is 
valid as long as the boot file on the specified physical volume is not deleted. The comments 
for the validity of returned BootLocations in GetFileLocation also apply here. 
TemporaryBooting.InvalidParameters will be raised if the specified volume does not have a 
Pilot boot file installed on it. GetPVLocation may also raise 

PhysicalVoiume.Error[physicalVolurneUnknown]. 

TemporaryBooting.OutLoadlnLoad: PROCEDURE [ 

OUtloadLocation: file TemporaryBooting.BOOtLocation, 
inloadLocation: TemporaryBooting.BOOtLocation, 
pMicrocode, pGerm: long pointer nil, 
countGerm: Environment.PageCount0, 
switches: System.Switches *-System.defaultSwitches]; 

TemporaryBooting.OutLoadlnLoad is an atomic operation; that is, nothing happens between 
the outload and inload. The state of the currently running system is saved on 
outloadLocation. The system represented by inloadLocation is restored to a running state. 
The microcode and/or germ may be changed by passing the appropriate information in 
pMicrocode, pGerm and countGerm. If pMicrocode is defaulted, the microcode is not 
changed. If pGerm is defaulted, the germ is not changed. The switches are available to the 
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inloaded Pilot. These are typically examined only when the system being booted is not an 
outload file (e.g., it was made by MakeBoot). Note that the switches may be ignored if 
inloadLocation is a bootButton BootLocation. Upon return, the following sequence has 
occurred: (1) Pilot has successfully performed the outload and has executed the inloaded 
system: (2) at a later time a client, (possibly a different one), has inloaded the state of the 
original system (the one outloaded in (1)). 
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A backstop is a system for recording information about sick software and hardware For 
product systems, it is installed instead of a debugger, and receives control in the same way 
and at the same times that a debugger would. When the backstop is invoked, it records the 
error and a restart message in a backstop log file and reboots the debug gee system. The 
debuggee system may then read the restart message from the backstop log and inform the 
user as to what has happened. The interface Backstop supplies facilities for implementing 
a backstop. The interface BackstopNub supplies facilities for reading entries from a log 
file written by a backstop. 

The implementation modules are Backs toplmpl . bed and BackstopNublmpl . bed. 
When these modules are used, the object Files VMMapLoglmpl . bed, MemCacheNub .bed, 
and BSMemCache . bed must also be bound in. In the following description, the term 
backstop core refers to the facilities provided by these interfaces. The term backstop 
control refers to the software built on top of it to implement a complete backstop system. 
Where the meaning is unambiguous, the term backstop may be used for either or both. 

9.1 Implementing a backstop 

The facilities in the Backstop interface are used to implement a backstop. The backstop 
core uses the Pilot logging facilities (Log) for recording the error information and the 
restart message in the backstop log file. 

The implementation module Backs topNublmpl. bed exports the interface 
BackstopNub and can be used for reading backstop logs. It uses the facilities of the Log 
and LogFiie interfaces, so clients of BackstopNub must ensure that these interfaces are 
exported to BackstopNublmpl. 

The following kinds of errors are reported to a backstop: 

Address faults 
Write protect faults 
Uncaught signals and errors 

Direct calls: Runtime.CallDebugger and Runtime.lnterrupt 

Operations are provided to determine the type of error and to record sufficient information 
in the log to later identify the source line in the procedure and module which caused the 
error. Parameters accompanying signals, errors, and direct calls are also recorded. 
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Additional information about the currently running processes and their call stacks can 
also be recorded. 


9.LI Initializing a backstop log file 

The following procedure is used to initialize a backstop log file. 

Backstop.CreateBackstopLog: procedure [size: cardinal, file:Fiie.File, 
firstPageNumber: File.PageNumber <-0]; 

file will be initialized as a backstop log. firstPageNumber indicates the number of pages 
over which the backstop should skip before it starts writing its data. 

9.1.2 Control flow 

A backstop receives control when its volume is booted or when its client tries to go to the 
debugger. The backstop may be booted to create a new log file, read an existing log file, or 
perform some other maintenance task. A boot switch should be used when booting a 
backstop to perform the maintenance tasks so that the backstop control software can 
determine why it received control Whenever the backstop is booted, control enters the 
backstop when Pilot calls PilotClient.Run. 

When the backstop is installed, it may raise the signals Volume. InsufficientSpace or 
Volume.RootDirecforyError in the process of creating its outload file. 

A backstop must pass control to the debuggee system by calling Backstop.Proceed 

Backstop.Proceed: procedure [boot: volume.ID]; 

boot specifies the volume to be restarted. If boot is volume.nulllD, the physical volume will 
be booted. 

Backstop.VersionMismatch: signal; 

VersionMismatch indicates that the version of Pilot in the backstop is different from that 
in the product system, and that the backstop may not record meaningful error 
information. This could occur if a new version of a debuggee system was installed without 
also installing a compatible version of the backstop. VersionMismatch will be raised by 
the first Backstop procedure called that examines the client. 

9.1.3 Logging errors 

Procedures in this section are used to write information into the current backstop log file 
about the state of the product system when an error occurs. These are the only procedures 
that may be used to write entries into a backstop log file (do not use Log.PutBlock, etc.). 
The backstop control software may use LogFile. Restart to communicate with the debuggee 
system. It may also use LogFile. GetLost, etc., to determine the state of the current backstop 
log file. These procedures may raise the signal VersionMismatch. 

Backstop.LogError: procedure []; 
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Backstop.GetError: procedure returns [BackstopNub.ErrorType]; 

BackstopNub.ErrorType: type = machine dependent { 

addressfault, writeprotectfault, signal, call, unused, interrupt, other, bug}; 

Backstop.NotLoggingError: error, 

LogError records the type of error that caused the backstop to be invoked, along with the 
information necessary to locate the error in the source code and any parameters of the 
error. It also does a Log.SetRestart, recording the index of the log entry it wrote and the 
current time. GetError returns the type of the current error. These operations and all 
operations in this section can only be used when the backstop is invoked to process an 
error. If they are called when not processing an error, they will raise NotLoggingError. 

The following procedures can be used to enumerate all of the debuggee's active processes 
and log the state of each one. The current process can also be identified. 

Backstop.GetNextProcess: procedure [process: Backstop.Process] 
returns [next: Backstop.Process]; 

Backstop.GetCurrentProcess: procedure returns [process: Backstop.Process]; 
Backstop.GetFaultedProcess: procedure returns [process: Backstop.Process]; 
Backstop.LogProcess: procedure [process: Backstop.Process]; 

Backstop.nullProcess: readonly Backstop.Process; 

Backstop.Process: type [1]; 

Backstop.NotAFault: error; 

GetNextProcess is a stateless enumerator that begins and ends with nullProcess. 
Processes are returned in order beginning with the handle of the process that caused the 
error. GetCurrentProcess returns the handle of the process that caused the error. 
GetFaultedProcess returns the handle of the process that took the fault when the error 
type is addressfault or writeprotectfault. If GetFaultedProcess is called for some other 
error type, the signal NotAFault is raised. LogProcess records information about the state 
of its argument process in the current backstop log file. 

Once a process is obtained, the following procedures can be used to enumerate the frames 
in its call stack, starting with the most recently called procedure, and log the state of each 
one. 

Backstop.GetNextFrame: procedure [process: Backstop.Process, frame: Backstop.Frame] 
returns [next: Backstop.Frame]; 

Backstop.LogFrame: procedure [frame: Backstop.Frame]; 

Backstop.nullFrame: readonly Backstop.Frame; 

Backstop.Frame: type [1]; 
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Passing nullFrame t.n GetNextFrame will return a handle for the local frame of the most 
recently called procedure of the process. Passing a handle so obtained will return a handle 
for the local frame of the next-most-recently-called procedure, and passing the handle of 
the root frame of the process will return nullFrame. LogFrame records information about 
the state of its argument frame in the current backstop log file. 

9.2 Reading backstop log Hies 

Facilities provided by the BackstopNub interface are used to enumerate the entries of a 
backstop log file and to read the information there. This might be done either by backstop 
control or by the debuggee system. The backstop log file is implemented using the Pilot 
logging facilities. Log.GetLost, etc., may be used to determine the state of the backstop log 
file. 

BackstopNub.GetNext: procedure [log: File.File, current: Log.lndex, 
firstPageNumber: File.PageNumber *- 0] 
returns [next: Log.lndex]; 

BackstopNub.GetSize: procedure [log: File.File, current: Log.lndex, 
firstPageNumber: File.PageNumber *— 0] 
returns [size: cardinal]; 

BackstopNub.GetLogEntry: procedure [log: File.File, current: Log.lndex, 
place: BackstopNub.Handle, firstPageNumber: File.PageNumber«- 0]; 

BackstopNub. NotErrorEntry: ERROR; 

BackstopNub.Handle: LONG POINTER TO BackstopNub.ErrorEntry; 

BackstopNub.ErrorEntry: type = machine dependent record! 
globalFrame(O): BackstopNub.GlobalFrame, 
pc(1): BackstopNub.PC, 
time(2):System.GreenwickMeanTime, 

Options(4): SELECT error(4): BackstopNub.ErrorType FROM 
signal = > [signal(5):BackstopNub.Signal, 
msg(6): BackstopNub.SignaiMsg, 
stk(7): array [0.,stackSize) of unspecified), 
call = > [msg(5): StringBody], 
unused = > [). 
interrupt = > [], 

addressfault = > [faultedProcess(5): BackstopNub.PSBIndex], 
writeprotectfault = > [faultedProcess(5): BackstopNub.PSBIndex], 
other = > [reason(5): BackstopNub.SwapReason], 
bug = > (bugType(5): cardinal], 
endcase]; 

BackstopNub.GlobalFrame: type [1],- 
BackstopNub.PC: TYPE [1 ]; 

BackstopNub.PSBIndex: TYPE [1]; 
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BackstopNub.Signal TYPE [2]; 

BackstopNub.SignalMsg: type [1], 

BackstopNub-SwapReason: TYPE [1]; 

GetNext is a stateless enumerator that begins and ends with log.nulllndex. Values are 
returned in the order that they were written to the file. GetSize returns the number of 
words of the current entry. An entry of type ErrorEntry is copied into the storage provided 
to GetLogEntry. firstPageNumber is the number of pages over which the backstop should 
skip before it starts reading the data. If any of these procedures are called with an index 
that does not correspond to a valid backstop log entry, they raise NotErrorEntry. 

No facilities are provided for reading process or frame entries. 
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10.1 Communication Diagnostics 

CommOnlineDiagnostics: definitions 

This interface is used by clients of communications online diagnostics. It includes 
procedures for gathering ethernet statistics, running echo tests and testing RS232C and 
dialer facilities. All tests may be run on any host machine exporting the communications 
online diagnostics server. 

CommOnlineDiagnostics.ServerOn: PROC; 

Calling ServerOn causes the local machine to export the communications online 
diagnostics. Any of the following diagnostics can then be run on the local machine from 
any other machine. 

CommOnlineDiagnostics.ServerOff: PROC; 

Calling ServerOff causes the local machine to unexport the communications online 
diagnostics. If a client attempts to run a diagnostic on a machine that is not exporting 
communications online diagnostics, the error CommError will be raised with a reason of 

noSuchDiagnostic. 

CommOnlineDiagnostics.CommE rror: error [reason: CommErrorCode]; 

CommError is raised by any of the diagnostics when an error occurs in the 
communications used to call the diagnostics. 

CornrnOniineDiagnostics.CommErrorCode: TYPE = MACHINE DEPENDENT { 
transmissionMediumProblem, 
noAnswerOrBusy, 
noRouteToSystemElement, 
transportTi meout, 

remoteSystemElementNotResponding, 

noCourierAtRemoteSite, 

tooManyConnections, 

invalidMessage 

noSuchDiagnostic, 
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returnTimedOut, 

callerAborted, 

unknownErrorlnRemoteProcedure, 

streamNotYours, 

truncatedTransfer, 

parameterlnconsistency, 

invalidArguments, 

protocol Mismatch, 

duplicateProgramExport, 

noSuchProgramExport, 

invalidHandle, 

noError}; 

CommErrorCode defines the type of fatal error that occurred. 


transmissionMediumProblem 


transmissionMediumProblem indicates 
some sort of problem with the physical 
device. 

This error applies to circuit oriented 
media only and indicates that the 
remote end did not answer or was 
already busy. 

noRouteToSystemElement indicates the 
network on which the diagnostic is to be 
run is not reachable at this time. 

This error code indicates the machine 
specified in the host parameter of the 
diagnostic is not responding. 

This error code indicates that the 
maximum number of courier 
connections has been reached. 

The remote service does not export the 
diagnostic specified. 

The rest of the error codes are translations of the Courier error codes that define Courier 
communication errors. See the Courier section for more details. 


noAnswerOrBusy 


noRouteToSystemElement 


remoteSystemElementNotResponding 


tooManyConnections 


noSuchDiagnostic 


10.1.1 Ethernet echo testing 

EchoDiagHandle:TYPE = LONG POINTER TO echoDiagObject; 

EchoDiagObject: TYPE; 

CommOnlineOiagnostics.StartEchoUser: PROC [ 

targetSystemElement: System. NetworkAddress, 
echoParams: EchoParams, 
eventReporter: EventReporter <- nil, 

host: System.NetworkAddress *- System.nullNetworkAddress] RETURNS 

[dH:EchoDiagHandle] 

StartEchoUser starts the echo test. Multiple echo tests may be run on the same host. The 
dH returned from StartEchoUser is the handle to be used to retrieve the echo test results. 
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targetSystemElement 

echoParams 

eventReporter 


host 


targetSystemElement is the machine that is to be the echo 
server. 

echoParams are the client specified parameters for the test 
to be run. 

eventReporter is the client-supplied procedure that will be 
called whenever an interesting event occurs. An interesting 
event may be when an echo response is received, or when 
some kind of error occurs. If the client does not wish the 
kind of feedback provided by the event reporter, he should 
set the eventReporter to nil or let it default to nil. 
host is the network address of the machine that is to be used 
as the echo user. 


CommOnlineDiagnostics.GetEchoResultS: PROC [ 
dH:EchoDiagHandle; 
host: System.NetworkAddress, 

Stoplt: BOOLEAN] 

returns [totalsSinceStart: EchoResults, 
hist: Comm OnlineDiagnostics. H i StOg ra m ]; 

After starting the echo user, the client obtains the results of the test by calling 
GetEchoResults. The test is implemented with a "dead man's switch"--the client must call 
GetEchoResults within the safetyTOInMsecs that was passed in StartEchollser for the test 
to actively continue. Every echo test that was started with the StartEchoUser proc must 
eventually be terminated by a call to GetEchoResults with stoplt set to true, regardless of 
whether the test is actually sending. 

dH dH is the handle that identifies the test to retrieve the 

results from. 

stoplt If the procedure is called with stoplt equal to TRUE, the test 

will return the results and then stop. If the client wishes to 
obtain intermediate results of an echo test, he may call 
GetEchoResults with stoplt equal to false, the current 
counters will be returned, and the test will continue to run. 
This is useful for real-time feedback at time intervals 
chosen by the client. 

host host is the network address of the machine that is the echo 

user. 

totalsSinceStart totalsSinceStart are the actual results of the echo user test, 

hist hist is a histogram of the timing between the sending of the 

echo request and the receiving of the echo reply. 

CommOnlineDiagnostics.EchoEvent: TYPE = 

{success, late, timeout, badDataGoodCRC, sizeChange, unexpected}; 

Used with EventReporter for client feedback, EchoEvent defines the type of event that has 
just occurred in the echo test. 

success success indicates that the echo request/response exchange 

was successfully completed. 

late late indicates the response to the echo request arrived late. 
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timeout 


badDataGoodCRC 


sizeChange 


unexpected 


This event occurs when no response is received for the echo 
request sent. The test will timeout and send the next echo 
request. 

badDataGoodCRC indicates the echo response was received 
without a CRC error, but some data bytes of the packet do 
not match the expected pattern. 

If the test is varying the length the the data in the echo 
request, an event of sizeChange will occur when the size 
goes from the maximum back to the minimum, 
unexpected indicates that unsolicited packets were received 
on the echo socket before the echo test was actually started. 


CommOnlineDiagnostics.EchoParamS: TYPE = MACHINE DEPENDENT RECORD [ 

totalCount(O): cardinal «- last[cardinal], 
safetyTOInMsecs(1): long cardinal 60000, 
minPacketSizeinBytes(3): cardinal 2, 
maxPacketSizelnByte$(4): cardinal <- 512, 
wordContents(S): WordsInPacket *-incrWords t 
constant(6): cardinal <-1 25252 b, 
waitForResponse(7): boolean true, 
minMsecsBetweenPackets(8): cardinal <-o, 
checkContents(9): boolean «-true, 
showMpCode{10): boolean false]; 


EchoParams is used by the client to define the parameters desired for the echo test. 


totalCount 


safetyTOInMsecs 


minPacketSizelnBytes 
maxPacketSizel n Bytes 


totalCount indicates the number of echo request/response 
exchanges the client wishes the test to execute. After 
totalCount packets have been echoed, the test will wait in 
an idle state for the client to terminate it and to retrieve the 
results via GetEchoResults. Of course, the test may be 
terminated at any time (i.e., before totalCount packets have 
been echoed) via GetEchoResults. If this number is set to 0, 
the test will run until stopped by GetEchoResults or by the 
"dead man's” switch. 

safetyTOInMsecs is the timeout used in the test’s "dead- 
man’s switch.” After starting the echo test, GetEchoResults 
must be called within this time, to either reset the timeout 
and continue echoing or to stop the test and collect the 
results. If GetEchoResults is not called within this time, the 
test will enter an idle state. It must still be terminated via 
GetEchoResults. 

minPacketSizelnBytes is used to specify the minimum 
number of data bytes to send in the echo request. 
maxPacketSizelnBytes is used to specify the maximum 
number of data bytes to send in the echo request. If the 
specified size is larger then the maximum data bytes 
allowed in an echo packet, it will be truncated to the 
maximum allowed. If maxPacketSizelnBytes is equal to 
minPacketSizelnBytes, the test will send constant length 
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echo packets, otherwise the size will range from the 
minimum specified to the maximum. 

wordContents This parameter specifies what the data words in the packet 

will contain. 

constant The data word constant is set using the constant parameter. 

This parameter is used by the test only if the wordContents 
parameter is allConstant. 

waitForResponse If waitForResponse is true, the test will not send an echo 

request until the reply to the previous request is received or 
a timeout occurs. 

minMsecsBetweenPackets The client can set the approximate interval between 

echo requests by specifying minMsecsBetweenPackets. 
checkContents Client may have the test verify each word in the echo 

response packet by specifying checkContents. 
showMpCode This parameter is currently unimplemented. 

CommOnlineDiagnostics.EchoResultS: TYPE = MACHINE DEPENDENT RECORD [ 

totalAttempts, successes,timeouts, late, unexpected: long cardinal, 
avgDelaylnMsecs: long cardinal, 

okButDribble, badAlignmentButOkCrc, packetTooLong, overrun, idlelnput, 
tooManyCollisions, lateCollisions, underrun, stuckOutput: long cardinal]; 

Returned by the GetEchoResults procedure, EchoResults is the results of the ethernet echo 

test. It includes statistics obtained from the ethernet during the test. 

totalAttempts totalAttempts is the total number of echo packets that the 

echo user attempted to send, regardless of the number of 
valid responses received. 

successes successes is the total number of successful echo 

request/response exchanges. 

timeouts timeouts is the number of times the test sent an echo 

request, and did not receive the response before timing out 
and sending the next request. 

late late is the number of echo responses that arrived at the echo 

user late. 

unexpected unexpected is the number of unexpected packets that were 

received on the echo socket. 

avgDelaylnMsecs The avgDelaylnMsecs is the average time between 

successful echo request/response exchanges. 

okButDribble, badAlignmentButOkCrc, packetTooLong, overrun, idlelnput, 
tooManyCollisions, lateCollisions, underrun, stuckOutput 

These ethernet statistics are the number of packets found 
with the specified problem. Note: These statistics are only 
valid for echo tests using ethernets, and should be ignored 
for other mediums. 

CommOnlineDiagnostics.EtherDiagError: error [reason: EtherErrorReason]; 
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Raised by the ethernet diagnostics, EtherDiagError indicates an error has occurred which 
prohibits the test from starting or continuing. The reason parameter indicates what type 
of fatal error has occurred. 

CommOnlineDiagnostics.EtherErrorReaSOn: TYPE = MACHINE DEPENDENT { 
echollserNotThere, 
noMoreNets, 
invalidHandie}; 

EtherErrorReason defines the fatal errors that can occur in the ethernet echo test, 
retrieving echo counters and the gathering of ethernet statistics. 

If GetEchoResults is called when there is no echo test 
running on the host machine, an error will be raised with a 
reason of echollserNotThere. 

Raised by GetEthernetStats, noMoreNets indicates that 
there is no existing net with the physicalOrder specified. 
Raised by GetEchoResults, invalidHandie indicates the 
client attempted to retrieve results with an already active 
handle. 

CommOniineDiagnostics.EventReporter: type = procedure [event: EchoEvent]; 

Clients who wish to be notified at every echo event can implement a EventReporter 
procedure. This procedure is passed to StartEchoUser, and is called whenever an 
interesting event occurs, usually at the successful or unsuccessful completion of a echo 
request/response exchange. 

CommOnlineDiagnostics.HistOgram: TYPE = LONG DESCRIPTOR FOR ARRAY CARDINAL OF Detail; 

Detail: type = RECORD[msec, count: cardinal]; 

A Histogram is used for the data of the histogram that the echo test builds. Each element 
of the histogram is a Deta i I. 

msec msec is chosen by the echo test, msec for the current 

element of the histogram and msec for the previous element 
specifies an interval in which echo packets complete a round 
trip. 

count The count is the number of packets that were sent and 

returned in the interval defined by the value of msec and 
the value of msec for the previous element of the histogram. 

CommOnlineDiagnostics.WordsInPacket: TYPE = MACHINE DEPENDENT { 
allOs(O), allls(l), incrWords(2), allConstant(3), dontCare(4)}; 

The data content of the echo request is defined by WordsInPacket. 

allOs allOs means the words in the packet will contain zeros, 

allls allls means the words in the packet will contain ones. 

incrWords incrWords means each word of the packet will be 

incremented, starting with the first word equal to one. 


echoUserNotThere 

noMoreNets 

invalidHandie 
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allConstant allConstant means the words in the packet will be a client 

specified constant. 

dontCare dontCare means the client does not care what the data 

content of the packet is. 


10.1.2 Gathering Ethernet statistics 

CommOnlineDiagnostics.EtherStatSlnfO: TYPE = ARRAY Statslndices OF LONG CARDINAL; 


EtherStatsInfo is the statistics collected for the ethernet since the last system restart. 

CommOniineDiagnostics.StatsIndices: type = {echoServerPkts, EchoServerBytes, 

packetsRecv, wordsRecv, packetsMissed, badRecvStatus, okButDribble, badCrc, 
badAlignmentButOkCrc, crcAndBadAlignment, packetTooLong, overrun, idlelnput, 
packetsSent, wordsSent, badSendStatus, tooManyCollisions, lateCollisions, 
underrun, stuckOutput, collO, colli, coll2, coll3, coll4, collS, coll6, coll7, coll8 f coll9, 
colllO, colli 1, colli 2, coll 13, colli 4, colli 5, spare}; 


Each item in the Statslndices represents the specified ethernet statistic. 


echoServerPkts 

EchoServerBytes 

packetsRecv 

wordsRecv 

packetsMissed 

badRecvStatus 

okButDribble 

badCrc 

badAlignmentButOkCrc 

crcAndBadAlignment 

packetTooLong 

overrun 

idlelnput 

packetsSent 


The number of packets that the machine has echoed is 
indicated by echoServerPkts. 

The number of bytes that the machine has echoed is 
indicated by EchoServerBytes. 

packetsRecv indicates the total number of packets that have 
been successfully received, including echo packets. 
wordsRecv indicates the total number of words that have 
been successfully received, including words in echo packets. 
packetsMissed is the number of packets that have been 
dropped for lack of buffering. 

badRecvStatus is indicates the total number of packets that 
were not successfully received. 

okButDribble indicates the number of packets that were 
successfully received, but had extra bits at the end. 
badCrc indicates the number of packets that were received 
with bad CRCs. 

badAlignmentButOkCrc indicates the number of packets 
that were received with correct CRCs, but did not end on byte 
boundries. 

crcAndBadAlignment indicates the number of packets that 
were received with bad CRCs and did not end on byte 
boundries. 

packetTooLong indicates the number of packets received 
that were long than the maximum internet size of 576 bytes, 
overrun occurs when the microcode cannot take bits out of 
the input silo fast enough to keep up with the bits coming in 
of the wire. 

idlelnput indicates the number of times the machine did not 
receive input from the ethernet for at least 40 seconds. 
packetsSent indicates the total number of packets that have 
been successfully sent, including echo packets. 
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wordsSent wordsSent is the total number of words sent, including 

those in echo packets. 

badSendStatus badSendStatus indicates the total number of packets that 

were not successfully sent. 

tooManyCollisions tooManyCollisions indicates the number of packets that 

were never sent after sixteen attempts failed because of 
collisions. 

lateCollisions lateCollisions indicates the number of packets which have 

had collisions occur in the later part of the packet (after bit 
512). 

underrun underrun occurs when the microcode cannot put bits into 

the output silo fast enough to maintain the 10Mbit rate. 
stuckOutput stuckOutput indicates thes number of tiem the machine was 

unable to send a packet in 2.5 seconds. 

collO, colli, col 12 # coll3, coll4 r coll5, coll6, coll7, coll8, coll9, colllO, colli 1, colli 2, 
coll13, coll14, colli5 Each of these items indicates the number of packets that 

were sent after the specified number of collisions. 

CommOnlineOiagnostics.GetEthernetStatS: PROC [ 
physicalOrder: cardinal <-i, 

host: System.NetworkAddress «-System.nullNetworkAddress] 
returns [info: CommOnlineDiagnostics.EtherStatsInfo, 
time: System.GreenwichMeanTime]; 

Calling GetEthernetStats obtains the ethernet statistics since the last system restart from 
the machine. 

physicalOrder is the number of the device on the device 
chain. The primary network has a physical order of one. 
host is the machine from which to obtain the statistics. 

The current ethernet statistics are returned in stats, 
time is the time the snapshot of the stats was taken. The 
client may make multiple calls to GetEthernetStats and use 
the times returned to calculate the number of echoed 
packets in a certain time interval. 

CommOnlineDiagnostics.GetEchoCounters: PROC [ 

host: System.NetworkAddress <-$ystem.nullNetworkAddress] 

returns [packets, bytes: long cardinal, time: System.GreenwichMeanTime]; 

To obtain the number of packets which the echo server on the specified machine has 
echoed since the last system restart, clients may call GetEchoCounters. The additional 
parameter host in the RemoteCommDiags procedure is the network address of the 
machine from which to collect the echo counters. 

host host is the network address of the machine from which to 

collect the echo counters. 

packets packets is the number of echoed packets. 

bytes bytes is the total number of bytes the server has echoed. 

time time is the time the statistics were collected. The client may 

make multiple calls to GetEchoCounters and use the times 


physicalOrder 

host 

stats 

time 
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returned to calculate the number of echoed packets within a 
certain time interval. 


10,1.3 RS232C testing 

RS232C testing consists of running a loopback test that exercises and verifies the data- 
transmission/reception features of the RS232C channel. As the client is required to set 
some of the channel characteristics, he should be familiar with the EIA RS232C standard. 

CommOnlineOiagnostics.StartRS232CTest: PROC [ 
rs232cParams: RS232CParams, 
setDiagnosticLine: SetDiagnosticLine <-nil, 
writeMsg: WriteMsg <-nil, 
modemChange: ModemChange «-nil, 
host: System.NetworkAddressSystem.nullNetworkAddressJ; 

The test is run by calling StartRS232CTest and requires that a loopback plug be installed 
on the RS232C cable. The parameters specified by the client in the StartRS232CTest test 
are concerned with defining the transmission medium usage and the session 
characteristics. 


Multiple RS232C tests may be run on the same machine, but only one per port. Calling 
StartRS232CTest on an already active port will result in the error RS232CDiagError with 
the code channellnUse. 


setDiagnosticLine 


writeMsg 


modemChange 


host 


setDiagnosticLine is used only by CIU diagnostic 
implementors for resetting the port for running the 
loopback test. Other clients should set it to NIL. 
writeMsg is a client-supplied procedure for realtime 
feedback, called after a frame has been sent and received 
through the loopback. Clients who are not interested in this 
kind of feedback should set this parameter to nil. 
modemChange is a client-supplied procedure for realtime 
feedback, called whenever any of the ModemSignals 
changes state. Clients who are not interested in this state 
change should set this parameter to nil. 
host is the network address of the machine on which to run 
the diagnostic. 


CommOnlineDiagno$tics.GetRS232CResultS: PROC [ 

StOpIt: BOOLEAN, 

host: System.NetworkAddress *-System.nullNetworkAddress] 
returns [counters: CountType]; 


After starting the loopback test, the client obtains the results of the test by calling 
GetRS232CResults. The test is implemented with a "dead mans switch" - the client must 
call GetRS232CResults with safetyTOInMsecs that was passed to the StartRS232CTest 
procedure in order for the test to continue. Clients must eventually terminate the 
loopback test by calling GetRS232CResults with stopIt equal to true. 

stopIt If the procedure is called with stopIt equal to true, the test 

will return the results and then terminate. If the client 
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wishes to obtain intermediate results of an echo test, he may 
call GetRS232CResults with stopit equal to false, the 
current counters will be returned, and the loopback test will 
continue to run. 

host host is the network address of the machine on which to run 

the loopback test. 

counters counters is the current results of the loopback test. 

CommOnlineDiagnostks.RS232CDiagError: error [reason: RS232CErrorReason]; 

The error RS232CDiagError is raised whenever a fatal error occurs during the test. The 
client should do the necessary clean up and end the test process. 

RS232CErrorReason: type = {aborted, noHardware, noSuchLine, channelinUse, 
unimplementedFeature, invalidParameter, invalidHandle}; 

The reason in the RS232CDiagError is defined by RS232CErrorReason. 

aborted indicates the channel has been aborted. 

This error reason will occur if there is no RS232C hardware 
present or if the RS232C channel code has not been started. 
noSuchLine indicates a bad RS232C line number has been 
specified by the client. 

If some other process is already using the RS232C port when 
the client attempts to start the RS232C test, the error will 
be raised with a reason of channelinUse. 

This error reason is used internally and should never be 
observed by the client. 

If an invalid parameter is passed to the RS232C test, the 
error will be raised with a reason of invalidParameter. 

This error indicates that the client called GetRS232CResults 
with a handle that had previously been deleted. 

CommOnlineDiagnostics.COUntType: TYPE = MACHINE DEPENDENT RECORD [sendOk, bytesSent, 
recOk,bytesRec, deviceError, dataLost, xmitErrors, badSeq, missing, sendErrors, 
recErrors: long cardinal]; 

CountType contains the counters used in the RS232CLoopback test. At the end of the test 
these counters are the results. The client may also check these counters during the test by 
calling GetRS232CResults with stopit equal to false. 

sendOk sendOk is a counter that reflects the number of successfully 

sent frames. 

bytesSent bytesSent is the current number of bytes that have been 

sent. 

recOk recOk reflects the number of successfully received frames. 

bytesRec bytesRec is the current number of bytes that have been sent. 

deviceError deviceError indicates the number of times data was received 

when no receive operation was outstanding. 
dataLost dataLost indicates the number of times that a incoming 

frame was too large to fit in the input buffer. 


aborted 

noHardware 

noSuchLine 

channelinUse 

unimplementedFeature 

invalidParameter 

invalidHandle 
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xmitErrors 


badSeq 


missing 


sendErrors 

recErrors 


xmitErrors indicates the number of frames that have been 
received with some sort of transmission error (e.g., 
checksum error, parity error, etc). 

badSeq indicates the number of times the receiver detected 
a frame with an unrecognizable sequence number. 
Generally this means that a frame has been lost or garbled 
during transmission. 

missing indicates the number of times the receiver has 
detected a missing frame from looking at the sequence 
numbers. 

sendErrors indicates the total number of frames that have 
not been successfully sent. 

recErrors indicates the total number of frames that have not 
been successfullyreceived. 


CommOnlineDiagnostics.LengthRange: type = record [low, high: [0..maxData)]; 
The range of data length (in bytes) in the frames is defined by LengthRange. 
CommOnlineDiagnostks.maxOata: CARDINAL = 1000; 


maxData is the maximum number of bytes of data in a frame. 

CommOnlineDiagnostics. ModemChange: TYPE = PROC [ 
modemSignal: ModemSignal: state: boolean]; 

ModemChange is a procedure type that is used by the client when he wishes to be notified 
when a change occurs in the state of the signals defined in ModemSignals. 

modemSignal modemSignal is the signal of interest, 

state state is the state of the signal. 

CommOniineDiagnostics.ModernSignal: type = {dataSetReady, clearToSend r 
carrierDetect, ringlndicator, ringHeard}; 

ModemSignal contain the state of the corresponding circuits described in EIA Standard 
RS232C. They are passed to the client through the procedure modemChange. 

CommOniineDiagnostics.PatternType: type = {zero, ones, oneZeroes, constant, bytelncr}; 

The PatternType defines the contents of the data in the frames being sent. 


zero 

ones 

constant 

bytelncr 


zero indicates the contents will be all zeros, 
ones indicates the contents will be all ones, 
constant indicates the test will use a client-supplied 
constant in each byte of data. 

bytelncr indicates the test will increment each byte of data 
in the frame, starting with a value of one. 


CommOnlineDlagnostics.RS 232 CParams: TYPE = MACHINE DEPENDENT RECORD [ 
testCount(O): cardinal *-last[long cardinal], 
safetyTOInMsecs(l): long cardinal <-6000, 
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lineSpeed(3): R5232cLineSpeed, 
correspondent^): RS232C.Correspondent, 

IineType(5): RS232cLineType, 
lineNumber(6): cardinal, 
parity(7): RS232CcParity, 
charLength(8): RS232cCharLength, 
pattern(9): PatternType, 
constant(10): cardinal o, 
dataLengths(ll): LengthRange 
dockSource{13):RS232CclockSource, 
waitForDSR(14):BOOLEAN <-true]; 

The parameters passed to the RS232C test are defined by the RS232CParams. 


testCount 


safetyTOInMsecs 


lineSpeed 

correspondent 


lineType 

lineNumber 


parity 

charLength 


pattern 

constant 


clockSource 

dataLengths 


testCount specifies the number of frames to send/receive. If 
this number is set to 0, the test will run actively loopback 
until stopped by the GetRS232CResults or by the "dead 
man’s” switch. 

safetyTOInMsecs is the timeout used in the test’s 
"deadman’s switch.” After starting the RS232C test by 
calling StartRS232CTest, GetRS232CResults must be called 
within this time, to either reset the timeout and continue 
echoing or stop the test and collect the results. 

The lineSpeed is the speed of the line and should agree with 
the setting of the modem. 

correspondent specifies a type of system the test is to 
"correspond” with. The line type determines what the 
correspondent should be. For a line type of asynchronous, 
ttyHost should be used. For bit synchronous, 
nsSystemElement should be used, and for byte synchronous, 
system6. 

lineType is the type of line the channel will use. 
lineNumber is the number of the RS232C line and should 
normally be set to 0. Other values apply only to processors 
with multiple RS232C lines, 
parity is the parity to use during the test. 

The character data length, (excluding parity, stop and start 
bits), is specified by charLength and should agree with the 
setting on the modem. 

The contents for each byte of data is specified by pattern. 

If the client has specified a pattern of constant, the constant 
parameter is used to specify what the data constant should 
be. 

clockSource determines whether the clock will be provided 
by the DTE (internal) or by the modem (external). 
dataLengths specifies the range of data lengths to send in 
the frames. If the low and high are equal, the test will send 
constant length data. If they are not equal, the test will first 
send the frame of the right length, decrementing the length 
with each subsequent send. 
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waitForDSR There are some modems in the field that do not raise DSR. 

This parameter enables users of such modems to tell the test 
to start even if DSR has not come up. 

CommOnlineOiagno$tics.RS232CTestMessage: type = {looped,sendError,recError}; 

The RS232CTestMessage is passed to the client-supplied procedure that is called every 
time a frame is sent/received. The message indicates the status of the transfer. 

sendError sendError indicates there has been some sort of 

transmission error. 

recError If errors occurred when the frame was received, the message 

will indicate recError. 

CommOnlineOiagnostics.SetDiagnosticLine: type = proc [lineNumber: cardinal] 

RETURNS [lineSet: boolean]; 

SetDiagnosticLine is a type used by the CIU implementors to reset the port when 
diagnostics are started. lineNumber is the line to set; lineSet indicates whether the reset 
was successful. 

CommOnlineDiagnostks.WriteMsg: type = PROc[msg: RS232CTestMessage]; 

WriteMsg is a procedure type that is used by the client when he wishes real-time feedback 
during the RS232C test. The msg parameter indicates the type of event that just occurred. 

10.1.4 Dialer testing 

This test is used to verify correct operation of the RS366 hardware and an external auto- 
dialer. The RS366 cable must be connected to the auto-dialer. 

CommOnlineDiagnostics.DialupTest: PROC [ 
rs232ClineNumber: cardinal, 

phoneNumber: long pointer to Dialup.Number,dialerType:diaiup.DialerType, 
host: System.NetworkAddress System.nullNetwork Address] 
returns [outcome: DialupOutcome]; 

DialupTest is called to test the dialer. The test will retry the dial a maximum of three" 
times before returning to the client. The additional parameter host in the 
RemoteCommDiags procedure specifies the network address of the machine on which to 
run the test. 

rs232ClineNumber 


phoneNumber 


rs232ChneNumber specifies the line number to bemused and 
should be set to 0. Other values apply only to processors 
with multiple RS232C lines. 

phoneNumber is the number to be used to call the foreign 
device. Note: The dialup implementation attaches no 
semantics to any of the bit patterns specified in 
phoneNumber, simply passing them to the dial hardware. 
Clients and/or their users must determine what the special 
characters (such as EON and SEP) are for their particular 
hardware and pass those characters to the dialup test. 
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dialerType dialerType is the type of dialing equipment being used, 

outcome outcome is the result of the dialup test. 

ComrnOnlineOiagnostics.DialupOutCOme: TYPE = { 

success, failure, aborted, formatError, transmissionError, dataLineOccupied, 
dialerNotPresent, dialingTimeout, transferTimeout, otherError, noHardware, 
noSuchLine, channellnUse, unimplementedFeature, invalidParamater}; 

DialupOutcome defines the result of the DialupTest. 


success success indicates the dialing operation was successful. This 

means all the digits in the number were dialed, and control 
was successfully transferred to the modem. 

If the dialing operation resulted in no answer, a busy signal, 
or the telephone was answered by something other that a 
compatible modem, the outcome will be failure, 
aborted is currently not implemented. 
formatError indicates the parameter phoneNumber was 
formatted incorrectly. 

transmissionError indicates the transfer of the dialing 
information to the dialing hardware did not succed. This 
outcome indicates a hardware problem. 
dataLineOccupied indicates the telephone line to which the 
dialing hardware is connected is off-hook. 

This outcome indicates the lack of working dialer hardware. 
An outcome of dialingTimeout indicates a hardware 
problem - the dialer did not respond to a request during 
dialing. 

transferTimeut indicates that no meaningful reply was 
received from the dialer following dialing the last digit. 
This outcome indicates a hardware problem. 
otherError means an unknown, unexpected error occurred. 
noHardware, noSuchLine, channellnUse, unimplementedFeature, invalidParamater 

These errors are used internally and should never be 
observed by the client. 


failure 


aborted 

formatError 

transmissionError 


dataLineOccupied 

dialerNotPresent 

dialingTimeout 


transferTimeout 


otherError 


10.2 Bitmap Display, Keyboard, and Mouse Diagnostics 

OnlineDiagnostics: definitions ...; 

This interface is used by clients of the bitmap Display, Keyboard, and Mouse Online 
Diagnostics. It includes procedures for running the bitmap Display Diagnostics, the 
Keyboard Diagnostics and the Mouse Diagnostics. 

OnlineDiagnostics.Background: type = {white, black}; 

Defines the background on the bitmap Display. 

OnlineDiagnostics.CursorArray: type = array [0..16] OF WORD; 

Defines the size and bit pattern of the cursor for display on the bitmap Display. 
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OnlineDiagnostics. Coordinate: TYPE = MACHINE DEPENDENT RECORD [x, y: INTEGER]; 

The bitmap Display is addressed by x-y coordinates. The coordinate origin (0, 0) is the 
uppermost, leftmost pixel of the display; x increases to the right and y increases 
downward. 

OniineDiagnostics.KeyboardType: type = {american, european, japanese}; 

Defines the type of keyboard being used. 

OnlineDiagnostks.KeyboardAndMouseTest: procedure [ 
keyboardType: OniineDiagnostics.KeyboardType, 
screenHeight: cardinal [0..32767], 
screenWidth: cardinal [0..32767], 

SetBackground: proc [background: OniineDiagnostics.Background], 

SetBorder: PROC[oddPairs, evenPairs: [0..377B]], 

GetMousePOSition: PROC RETURNS [OnlineDiagnostics.Coordinate], 

SetMousePosition: proc [newMousePosition: OnlineDiagnostics.Coordinate], 
SetCursorPattern: proc [cursorArray: OniineDiagnostics.CursorArray], 

SetCursorPosition: proc [newCursorPosition: OnlineDiagnostics.Coordinate], 
keyboard: long pointer. 

Beep: proc [duration: cardinal], 

ClearDisplay: proc, 

BlackenScreen: proc [x, y, width, height: cardinal], 

InvertScreen: proc[x, y, width, height: cardinal], 

WaitForKeyTransition: proc]; 

The KeyboardAndMouseTest procedure is used to run keyboard and mouse diagnostics 
using a bitmap display. 

screenHeight defines the number of horizontal lines on the bitmap 

Display. Equivalent to UserTerminal.screenHeight. 

screenWidth Defines the number of horizontal dots across the bitmap 

Display. Equivalent to UserTerminal. screenWidth . 

SetBackground [background: ...] Lets the bitmap Display background to either 

white or black. Equivalent to UserTerminal. SetBackground. 

SetBorder If the display has a border, then clients may set the pattern 

to be displayed in the border by calling this procedure. 
Equivalent to UserTerminal. SetBorder. 

GetMousePosition[ ] gets the x and y values of the mouse position. 

SetMousePosition modifies the x and y values of the mouse position. 

Equivalent to UserTerminal. SetMousePosition. 

SetCursorPattern sets up the bit pattern of the cursor for display on the 
bitmap Display. Equivalent to 

UserTerminal. SetCursorPattern. 
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SetCursorPosition sets the position of the cursor on the bitmap Display. 

Equivalent to userTerminai. SetCursorPosition. 


keyboard 

Beep 


OearDisplay 

BlackenScreen 


InvertScreen 


Equivalent to UserTerminai. keyboard. 

emits a tone from the speaker for the given duration of 
time. Duration is in milliseconds. Equivalent to 

UserTerminai. Beep. 

turns the entire screen white 

turns the screen black for the given width and height 
starting at the x/y coordinates. 

inverts the screen for the given width and height starting 
at the x/y coordinates. 


WaitForKeyTransition waits for an entry from the keyboard before returning (not 

presently used in Star). 

OnlineDiagnostics.NextAction: type = {nextPattern, invertPattern, quit}; defines the next 
action to be taken. Used with the bitmap Display alignment pattern. 

OnlineDiagnostics.LFDisplayTestlPROCEDURE [ 
screenHeight: cardinal [0..32767], 
screenWidth: cardinal [0..32767], 

SetBackground: proc [background: OniineDiagnostics.Background], 

SetBorder: proc [oddPairs, evenPairs: [0..377B]], 

GetNextAction: PROC RETURNS [OnlineDiagnostics.NextAction], 

OearDisplay: proc, 

BlackenScreen: proc [x, y, width, height: cardinal], 

FillScreenWithObject: PROc[p: long pointer to array [0..16) of word]]; 


The LFDisplayTest procedure displays test patterns on the display. It can be used as a 
bitmap Display alignment tool. 


screenHeight 

screenWidth 

SetBackground 

SetBorder 

GetNextAction 


defines the number of horizontal lines on the bitmap 
Display. Equivalent to UserTerminai. screenHeight. 

defines the number of horizontal dots across the bitmap 
Display. Equivalent to UserTerminai. screenWidth . 

sets the bitmap Display background to either white or 
black. Equivalent to UserTerminai. SetBackground. 

if the display has a border, then clients may set the pattern 
to be displayed in the border by calling this procedure. 
Equivalent to UserTerminai. SetBorder. 

gets the next action through keyboard input from the user. 
See OnlineDiagnostics.NextAction above. 
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ClearDisplay erases the entire display to white. 

BlackenScreen turns the screen black for the given width and height 

starting at the x/y coordinates. 

FillScreenWithObject fills the entire screen with the bit pattern in the 16 word 

array. 

10.3 Lear Siegler Diagnostics 

OnlineDiagnostics: DEFINITIONS . .. ; 

This interface is used by clients of the Lear Siegler Online Diagnostics. It includes 
procedures for running the Lear Siegler Diagnostic. 

OnlineDiagnostics. LSMessage: TYPE * {kTermAdj, kTypeCharFill, kCTLC, kFillScreen, 
kTypeXHair, kEndAdj, kTermTest, kTestKey, kCTLStop, kLineFeed, kReturnKey, kLetter, 
kAndCTL, kEscape, kSpBar, kAndShift, kShColon, kShSemiColon, kTypeComma, 
kHyphen, kTypePeriod, kVirgule, kNumeral, kKey, kLearColon, kSemiColon, kShComma, 
kShHyphen, kShPeriod, kShVirgule, kAtSign, kLeftBracket, kBackSlash, kRightBracket, 
kCaret, kBreak, kShAt, kShLeftBracket, kShBackSlash, kShRightBracket, kShCaret, 
kShBreak, kllnknown}; 

Defines the message displayed on the screen when the given character is entered from the 
keyboard. 

OnlineDiagnostics. LSAdjuSt: PROCEDURE [ 

cancelSignal: signal, 

GetMesaChar: proc returns [character], 

PutCR: proc, 

PutMessage: proc [message: OniineDiagnostics.LSMessage, char: character 0C], 
PutMesaChar: proc [char: character]]; 

The LSAdjust procedure allows the user to adjust the Lear Siegler Display. 

cancelSignal is raised when the user enters a 'Control C’ on the 

keyboard. Equivalent to NSCommand.Canceh 

GetMesaChar gets the character entered on the keyboard by the user. 

Equivalent to. NSCommand. GetMesaChar. 

PutCR outputs a carriage return to the Lear Siegler Display. 

Equivalent to NSCommand.PutCR[TRUE]. 

PutMessage displays the given message on the Lear Siegler Display. 

Equivalent to. NSCommand. PutLine. Note: The default for 
char is used for the Lear Siegler diagnostic. 

PutMesaChar outputs a character to the Lear Siegler Display. 

Equivalent to. NSCommand. PutMesaChar. 
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OnlineOiagnostics.LST est: PROCEDURE [ 

cancelSignal: signal, 

GetMesaChar: proc returns [character], 

PutMessage: proc [message: OnlineDiagnostics. LSMessage, char: character OC]]; 

The LSTest procedure allows the user to test the Lear Siegler Display or equivalent. 

cancelSignal is raised when the user enters a 'Control C’ on the 

keyboard. Equivalent to NSCommand. Cancel. 

GetMesaChar gets the character entered on the keyboard by the user. 

Equivalent to. NSCommand. GetMesaChar. 

PutMessage displays the given message on the Lear Siegler Display. 

Equivalent to. NSCommand. PutLine. Note: For the diagnostic 
the default for char is taken. 

10.4 Floppy Diagnostics 

OnlineDiagnostics: DEFINITIONS . . . ; 

This interface is used by clients of the Floppy Online Diagnostics. It includes procedures 
for running the Floppy Diagnostic. 

OnlineDiagnostics. Floppy Message: TYPE ■ { 

cFirst, cCallCSC, cCloseWn, cEnsureReady, cExit, dnsDiffCleanDisk, dnsertCleanDisk, 
clnsertDiagDisk, dnsertWriteable, cNBNotReady, cOtherDiskErr, cRemoveCleanDisk, 
cRemoveDiskette, cLast, 

hFirst. hBusy, hExped, hExpec2m, hCRCI, hCRC2, hCRCerr, hDelSector, hDiskChng, 
hErrDetc, hGoodComp, hHead, hHeadAddr, hlllglStat, hlncrtLngth, hObserl, hObser2, 
hReadHead, hReadSector, hReadStat, hReady, hRecal, hRecalErr, hSector, hSectorAddr, 
hSectorCntErr, hSectorLgth, hSeekErr, hTimeExc, hTrack, hTrackO, hTrackAddr, 
hTwoSide, hWriteDelSector, hWritePro, hWriteSector, hLast, 

iFirst. iBadContext, iBadLabel, iBadSector, iBadTrackO, iCheckPanel, iCIERec, iCIeanDone, 
iCIeanProgress, iErrDet, iErrIMoCRCErr, iExerWarning, iFormDone, iFormProgress, 
iFormWarning, iHardErr, iHeadDataErr, ilnsertDiagDisk, ilnsertFormDisk, iOneSided, 
iRunStdTest, iSoftErr, iTnx, iTwoSided, iUnitNotReady, iVerDataErr, Hast, 

tFirst, tByteCnt, tCIERH, tClERS, tCIEVer, tCIEWDS, tCIEWS, tHeadDataErr, tHeadDisp, 
tHeadErrDisp, tSectorDisp, tStatDisp, tSummErrLog, tVerDataErr, tLast, 

yFirst, yDispSects, yDispExpObsData, yDoorJustOpened, yDoorOpenNow, 
yDoorOpenShut, yIsltDiagDisk, ylsItWrProt, yStillContinue, yStillSure, yLast}; 

Define the message keys used by the Floppy Diagnostic. 

OnlineDiagnostics. FloppyReturn: TYPE = { 

deviceNotReady, notDiagDiskette, floppyFailure.noErrorFound}; 
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Defines the type of returns from some of the Floppy Diagnostics tests. 

deviceNotReady is returned when the floppy drive is not ready and therefore cannot 
be tested. 

notDiagDiskette is returned when the floppy diskette is not a Diagnostics Diskette 
and therefore cannot be tested because it cannot be written on. 
floppyFailure is returned when a floppy hardware error is detected. 
noErrorFound is returned when the test runs successfully. 

OnlineOiagnostics. Field: TYPE = RECORD [ 

fieldName: OniineDiagnostics.FloppyMessage, fieldValue: unspecified]; 

Used for Floppy Diagnostics status display. 

OnlineOiagnostics. FieldDataType: TYPE = { 

boolean, cardinal, character, hexadecimal, hexbyte, integer, octal, string}; 

Defines the various types of data displayed by the Floppy Diagnostics . 

OnlineOiagnostics. FI oppy WhatToDoNext: TYPE = { 

continueToNextError, loopOnThisError, displayStuff, exit}; 

Defines the operator options for running Floppy Diagnostics command files. 

OnlineDiagnostics.SingleDouble: type = {single, double}; 

Defines the number of sides and data density of a floppy diskette. 

OnlineDiagnostics.SectorLength : type = {one28, two56, five12, one024}; 

Defines the number of bytes in a sector of a floppy diskette. Used in Floppy Diagnostics 

command files. 

OnlineDiagnostics.ErrorHandling: TYPE = { 

noChecking, stopOnError, loopOnError, continueOnError}; 

Defines the operator options for the handling of floppy errors in the Floppy Diagnostics 

command files. 

OnlineDiagnostics.DisplayFieldsPrOc: PROCEDURE [ 
fields: descriptor for array OF Field, 
title: OnlineOiagnostics.FloppyMessage <—tFirst, 
fieldType: OniineDiagnostics.FieldDataType, 
numberOfColumns: cardinal +- 3]; 

DisplayFieldsProc displays Floppy Diagnostics status. 

fields defines the names of the status bits and their boolean values. 

title defines the title of the display. 

fieldType defines the type of data being displayed. 

numberOfColumns defines the number of columns in which to display the data. 

OnlineDiagnostics.DisplayTablePrOC: PROCEDURE [ 

headers: descriptor for array OF OniineDiagnostics.FloppyMessage, 
rowNames: descriptor for array OF oniineoiagnostics.FloppyMessage , 
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values: descriptor for array of descriptor for array of unspecified, 
title: OnlineDiagnostics. Floppy Message*— tFirst, 
fieldType: OniineDiagnostics.FieldDataType]; 

DisplayTableProc displays an error/summary log. 

headers defines the name of each column in the error/summary log, 
rowNames defines the name of each entry in the error/summary log. 
title defines the title of the error/summary log. 
fieldType defines the type of data being displayed. 

OniineDiagnostics.DisplayNumberedTableProc: procedure [ 
values: long descriptor for array of unspecified, 
rowNameHeader: OnlineDiagnostics.FloppyMessage*- tFirst, 
title: OnlineDiagnostics.FloppyMessage*— tFirst, 
numOfColumns: cardinal, 
startNum: integer, 

fieldType: OniineDiagnostics.FieldDataType]; 

DisplayNumberedTableProc displays a table of numbers plus the number of entries 
displayed. 

values defines the actual numbers to be displayed. 

rowNameHeader defines the name of the entries displayed (Example: "Byte Count”), 
title defines the title of the table. 

numOfColumns defines the number of columns displayed. 
startNum defines the first of the number of entries displayed. 
fieldType defines the type of numbers being displayed. 

OnlineDiagno$tics.PutMessageProc:pROCEDURE [msg: OnlineDiagnostics.FloppyMessage]; 

PutMessageProc displays the given message to the operator. 

OnlineDiagnostics.GetConfirmationProc:PROCEDURE [ 
msg: OniineDiagnostics. Floppy Message]; 

GetConfirmationProc displays the given message to the operator and requests 
confirmation. 

OniineDiagnostics. YesOrNo: TYPE = {yes, no}; 

OniineDiagnostics. GetYesOrNoPrOC: PROCEDURE [ 

msg: OniineDiagnostics. FloppyMessage] RETURNS [OniineDiagnostics. YesOrNo]; 

GetYesOrNoProc displays a message to the operator and requests a yes or no response. 

OnlineDiagnostics.GetFloppyChoicePrOC: PROCEDURE 

RETURNS [OniineDiagnostics. FloppyWhatToDoNext]; 

GetFloppyChoiceProc gets an answer from the operator on how to proceed after an error 
has occured in the command file. 

OnlineDiagnostics.FloppyExerciser:PROCEDURE [ 

displayFields: OniineDiagnostics.DisplayFieldsProc, 
displayTable: OniineDiagnostics.DisplayTableProc, 
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displayNumberedTable: OniineDiagnostics.DisplayNumberedTableProc, 
putMessage: OniineDiagnostics.PutMessageProc, 
getConfirmation: OniineDiagnostics.GetConfirmationProc, 
getYesOrNo: OniineDiagnostics.GetYesOrNoProc, 
getFloppyChoice: OniineDiagnostics.GetFloppyChoiceProc]; 

FloppyExerciser thoroughly exercises the floppy disk hardware. See arguments described 
above. 

OnlineDiagnostics.FloppyStandardTest PROCEDURE [ 

displayFields: OniineDiagnostics. DisplayFieldsProc, 

displayTable: OniineDiagnostics. DisplayTableProc, 

displayNumberedTable: OniineDiagnostics.DisplayNumberedTableProc, 

putMessage: OniineDiagnostics.PutMessageProc, 

getConfi rmation: OniineDiagnostics.GetConfirmationProc, 

getYesOrNo: OniineDiagnostics. GetYesOrNoProc, 

getFloppyChoice: OniineOiagnostics.GetFloppyChoiceProc] 

RETURNS [floppyReturn: OniineDiagnostics. Floppy Return]; 

FloppyStandardTest runs a nondestructive floppy disk diagnostic. See arguments 
described above. 

OniineDiagnostics.FloppyCleanReadWriteHeads:PROCEDURE [ 
displayFields: OnlineDiagnostics.DisplayFieldsProc, 
displayTable: OnlineDiagnostics.DisplayTableProc, 
displayNumberedTable: OniineDiagnostics.DisplayNumberedTableProc, 
putMessage: OniineDiagnostics.PutMessageProc, 
getConfirmation: OniineDiagnostics.GetConf irmationProc, 
getYesOrNo: OniineDiagnostics.GetYesOrNoProc, 
getFloppyChoice: OniineDiagnostics.GetFloppyChoiceProc] 
returns [floppyReturn: OnlineDiagnostics.FloppyReturn]; 

FloppyCleanReadWriteHeads cleans the read/write heads of the floppy disk drive. See 
arguments described above. 

OnlineDiagnostics.FloppyFormatDiskette: PROCEDURE [ 
displayFields: OniineDiagnostics.DisplayFieldsProc, 
displayTable: OniineDiagnostics.DisplayTableProc, 
displayNumberedTable: OniineDiagnostics.DisplayNumberedTableProc, 
putMessage: OniineDiagnostics.PutMessageProc, 
getConfirmation: OniineDiagnostics.GetConfirmationProc, 
getYesOrNo: OniineDiagnostics.GetYesOrNoProc, 
getFloppyChoice: OniineDiagnostks.GetFloppyChoiceProc]; 

FloppyFormatDiskette formats a diskette using the IBM format. See arguments 
described above. 

OnlineDiagnostics.FloppyCommandFileTest:PROCEDURE [ 
density: OnlineDiagnostics.SingleDouble, 
sides: OnlineDiagnostics.SingleDouble, 
sectorsPerTrack: cardinal [8..26], 

SectOrLength: OniineDiagnostics. SectorLength, 
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errorHandling: OniineDiagnostics. Error Handling, 
cmdFile: long string, 

displayFields: OniineDiagnostics. DisplayFieldsProc, 

displayTable: OniineDiagnostics. DisplayTableProc, 

displayNumberedTable: OnlineDiagnostics.DisplayNumberedTableProc, 

putMessage: oniineDiagnostics.PutMessageProc, 

getConfirmation: OniineDiagnostics. GetConfirmationProc, 

getYesOrNo: OnlineDiagnostics.GetYesOrNoProc, 

getFloppyChoice: OniineDiagnostics. GetFloppyChoi ceProc]; 

FloppyCommandFileTest executes an operator-generated floppy command file. 
sectorsPerTrack indicates the number of sectors per track that are to be used. cmdFile are 
the Floppy commands that are to be executed. For the remaining arguments, see the 
descriptions above. 

OnlineDiagnostics.FloppyDisplayErrorLog: PROCEDURE [ 
displayFields: OniineDiagnostics.DisplayFieldsProc, 
displayTable: OniineDiagnostics.DisplayTableProc, 
displayNumberedTable: OniineDiagnostics.DisplayNumberedTableProc, 
putMessage: OnlineDiagnostics.PutMessageProc, 
getConfirmation: OniineDiagnostics.GetConfirmationProc, 
getYesOrNo: OnlineDiagnostics.GetYesOrNoProc, 
getFloppyChoice: OnlineDiagnostics.GetFloppyChoiceProc]; 

FloppyDisplayErrorLog displays a summary/error log of the prior executed tests. See 
arguments described above. 
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11.1 ARPARouter 

ArpaRouter is the interface for common, public types and procedures of the lower level 
Arpa Internet transport and internet facilities. 

11.LI Types and constants 
Port: Type[i]; 

Port is a TCP or UDP port as defined in the TCP and UDP protocol specifications, RFC 793 
and RFC 768. It is used for intra machine multiplexing, and is a paramater in many of the 
procedures in the interfaces to the Arpa protocol implementations. A Port can either have 
a well, known value (a value defined in ArpaConstants), or a unique value that is known to 
both sides of a connection or session only for the duration of that connection or session. 

InternetAddress: type[2); 

InternetAddress is an Arpa Internet address of any address class as defined in the IP 
protocol specification, RFC 791. InternetAddress is used by the low level communications 
as source and destination addresses for other hosts in the Internet. This type is a 
parameter in many of the procedures in the interfaces to the Arpa protocol 
implementations. 

unknownlnternetAddresS: READONLY InternetAddress; 

UnknownlnternetAddress can be used for initializing an InternetAddress and indicating 
an address that has not been set to a valid address. It is not a null address indicating the 
local machine or network. Such an address may not have 0 bits in the address class fields 
and should be obtained by other means. 

11.1.2 Procedures 

GetAddress: proc returns [InternetAddress]; 
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GetAddress returns the InternetAddress of the local machine. If the Internet address is 
not known, unknownlnternetAddress is returned. 

11.1.3 References 

RFC768 User Datagram Protocol, Postel, August, 1980. 

RFC791 Internet Protocol, Postel, September, 1981 . 

RFC793 Transmission Control Protocol, Postel, September, 1981 . 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.2 TcpStream 

TcpStream is the client interface to the implementation of TCP in the Arpa family of 
protocols. TCP provides a sequenced, error-free stream across interconnected 
communication networks with duplicate suppression and flow control. It is assumed that 
the client is familiar with the TCP protocol specification, RFC 793. 

11.2.1 Types and constants 

WaitTime: Type = long cardinal; 

WaitTime is used for establishing intervals for timeouts. It is always in milliseconds. 

defaultWaitTime: WaitTime a 60000; 

The default wait time of 60 seconds is taken from the maximum TCP packet lifetime. 

infiniteWaitTime: readonly WaitTime; 

infiniteWaitTime is used to have an operation never time out, or to declare there is no 
interest in processing timeouts. Any client using infiniteWaitTime should be prepared to 
cancel the affected process at some time. 

uniquePort: readonly ArpaRouter.Port; 

uniquePort is a unique port number that may be used in creating TCP streams when the 
client does not need a well known port number of the local end. 

Suspended: error [why: SuspendReason]; 

SuspendReason: type » { 

notSuspended, transmissionTimeout, noRouteToDestination, 
remoteServiceDisappeared, reset}; 

Suspended is raised if an already established connection is suspended for any reason. The 
only operation a client can (and must) do after receiving this error is Delete. It is also the 
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client's responsibility to cause an unwind so that TCP's state can be properly cleaned up 
before calling Delete. 

notSuspended is used for internal processing and should never be seen by the client. 

transmissionTimeout indicates that the remote end has not acknowledged data sent to it 
in a long time. The local end concluded that the remote has disappeared. 

noRouteToDestination indicates the the route from the local socket to the remote socket 
has disappeared and another could not be found to use. 

remoteServiceDisappeared is currently unused. 

reset indicates that a TCP reset message was received from the other end. 

Failed: signal [why: FailureReason]; 

FailureReason: type ■ { 
timeout, 

noRouteToDestination, 

noServiceAtDestination, 

emoteReject, 

tooManyConnections, 

precedenceMismatch, 

securityMismatch, 

optionMismatch, 

noAnswerOrBusy, 

noTranslationForDestination, 

circuitlnllse, 

circuitNotReady, 

noDialingHardware, 

dialerHardwareProblem}; 

Failed is the error that is raised when the connection could not be established. Since the 
connection was never established, the client should not attempt to Close or Destroy it after 
this error. 

timeout indicates that the connection could not be established within the amount of time 
the client specified in the timeout parameter to the Make procedure. 

noRouteToDestination indicates there is no route from the local socket to the target 
socket. 

remoteReject indicates that the connection had to be reset for one of two different 
reasons. Either a TCP reset packet was received from the remote, or a syn packet was 
received that acknowledged data was never sent. Though such a packet is probably a 
"stray," the integrity of the connection was jepordized, and it was reset. The client may 
want to try the operation again, in hopes the condition was transient. 

tooManyConnections indicates that the local machine cannot create the requested 
connection as too many already exist. 


11-3 




11 


TCP/IP Interfaces 


precedenceMismatch indicates that a connection attempt was made to the local machine 
with a precedence lower then that specified in the Listen or Make procedure. 

securityMismatch indicates that a connection attempt was made to the local machine with 
a security level lower then that specified in the Listen or Make procedure. 

noAnswerOrBusy. noTranslationForDestination, circuitlnUser, circuitNotReady, 
noDialingHardware, and dialerHardwareProblem refer to problems on circuit 
oriented networks and are not implemented. 

Closed: error; 

Closed indicates the client tried to issue a put or a close after already closing the 
connection. 

ListenTimeout: signal; 

ListenTimeout is raised by the Listen procedure if a connection request does not arrive 
within the interval specified by listenTimeout in the Listen procedure. The client may 
either decide to stop listening, or resume the signal to continue listening. 

CompletionCode: type ■ {normal, timeout, pushed, closing, endUrgent}; 

Returned from the get procedure, CompletionCode indicates the status of that get. Any 
status besides normal may have returned less data than requested by the client. The 
client should look at the byteCount return code from the get in these cases to determine 
the amount of data actually returned. 

normal indicates that the get completed normally, returning to the client after retrieving 
the amount of data requested. 

timeout indicates that the TCP waited the amount of time specified in the Make or 
subsequent setWaitTime, and the requested amount of data did not arrive. 

pushed indicates that the remote end pushed the data, causing it to be transmitted 
immediately from the remote, and causing the local get to return at the point in the 
stream when it noticed the pushed data. 

closing implies a push, and indicates the remote end has no more data to send and issued a 
close, causing the local get to return upon receipt of the close. 

endUrgent indicates the client (who was previously notified of an urgent via 
waitForUrgent) has reached the last byte of the data marked urgent. 

Precedence: type ■ machine dependent{ 

routine(O), priority, immediate, flash, flashOverride, criticEcp, 
internetControl, networkControl(7)}; 

Precedence is used to set the IP precedence option of the connection. The precedence 
values are defined in RFC 793. 
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Security: TYPE ■ long pointer to SecurityObj; 

SecurityObj: type = record [ 

level, compartment, handling: cardinal, tcc: ArpaRouter.TCC]; 

Security is used to set the IP security of the connection. Values for security are defined in 
RFC 793. 

11.2.2 Procedures 

Listen: proc[ 

localPort: ArpaRouter.Port, 

listenTimeout: WaitTime «- infiniteWaitTime, 

receiveTimeout: WaitTime «- defaultWaitTime, 

precedence: Precedence<— routine, 

security: Security«- nil, 

options: Environment.Block *- [nil, 0,0]] 

RETURNs[tsH : Handle]; 

The client must tell a passive TCP the port on which to listen and provide the process to do 
so. This is done with Listen. 

localPort is the port on which to listen for a connection request. 

options are the TCP options. It is the responsibility of the client to put the options into the 
options block in the proper format for TCP to use. If options are not to be used, this 
parameter should be a null block. 

precedence is the service precedence desired in the network. 

security is the required security for a connection. When TCP (through Listen) receives a 
connection request, it checks the precedence and the security and determines if it is 
allowed to honor the request. 

If the connection is honored, Listen creates the stream and returns it to the client in tsH. 
The client regains control only when Listen returns with a valid stream, or when 
listenTimeout is exceeded, raising the signal ListenTimeout. 

Make: proc[ 

local, remote: ArpaRouter.InternetAddress, 

localPort, remotePort: ArpaRouter.Port, establishConnection: boolean, 
timeout: WaitTime, precedence: Precedence, 
security: Security, options: Environment.Block] 
returns [tsH: Handle]; 

Make is the procedure used to solicit a TCP connection. 

local is the address of the local machine. Clients can set it to 
ArpaRouter.unknownlnternetAddress, and the TCP implementation fills in the correct 
address. 
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remote is the address of the machine to connect. It can be any machine in the Internet, 
including the local machine. 

localPort is the port on the local machine to use for the connection. It is commonly set to 

uniquePort. 

remotePort is the port on the remote machine to connect. This value may be a well known 
port number for some well known service in the Internet (see ArpaConstants), or a port 
known privately between apair of machines. 

establishConnection determines whether or not the connection is to be active or passive. 
If it is TRUE, the local end will actively solicit the connection. If it is false, the local end will 
passively listen for a connection request. Note that the Listen procedure is the usual 
method of creating a passive listener. 

timeout is the amount of time to wait for a connection to happen. If the timeout is 
exceeded, the Failed error is raised. 

precedence is the service precedence desired in the network. 

security is the required security on this connection. If the remote machine considered the 
specified precedence and security to be unacceptable, it rejects the connection attempt, and 
the error Failed is raised. 

options are the TCP options to be used. It is the responsibility of the client to put the 
options into the options block in the proper format for TCP. If options are not to be used, 
this parameter should be a null block. 

If the connection is successfully established (the error Failed is not raised), the return 
value tsH identifies a connection that is ready and willing to be used by the client. 
Operations on this stream are executed through the procedures in the object pointed to by 

tsH. 

Handle: type a long pointer to Object; 

Object: type * record [ 
destroy: PROc[tsH: Handle], 

put: proc [block: Environment.Block, push: boolean], 
get: proc [block: Environment.Block] 

returns [byteCount: cardinal, completionCode: CompletionCode], 

waitForUrgent: proc [block: Environment.Block], 

sendllrgent: proc [block: Environment.Block], 

close: PROc[tsH: Handle], 

setWaitTime: PROC[WaitTime], 

findAddresses: proc returns! 

localAddr, remoteAddr: ArpaRouter.InternetAddress, 
localPort, remotePort: ArpaRouter.Port]]; 

A Handle uniquely identifies a connection. Operations on this connection are executed by 
calls to the procedure fields in the Object. 

destroy deletes the TCP stream. Except under error conditions, clients should call the 
close proc before deleting the stream in order to close gracefully and insure proper 
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delivery/reception of the last piece of data. A call to destroy on a non-suspended stream 
without executing the closing protocol causes a TCP reset message to be sent to the remote 
end. destroy flushes all input and output queues and destroys all stream state 
information. After calling destroy, the stream handle is invalid and cannot be used again. 

put queues for transmission the block of client output data specified by block. If the client 
wishes to specify that the data be flushed out to the network instead of being buffered in 
the local TCP, push should be set to true. Indicating push not only prevents buffering at 
the local end, but also causes outstanding gets at the remote end to return immediately 
upon receiving the pushed data. Use push only when really needed, as it impacts the 
efficiency of the connection. Setting urgent marks the last byte of the block as the end of 
urgent data. 

get retrieves the specified amount of data from the stream and puts it in block. If the data 
is not pending, get waits the amount of time specified in the Make call (or subsequent 
setWaitTimes) for the data to arrive from the remote. byteCount is the actual number of 
bytes transferred, as the client may not get the amount of data requested if the wait time 
is exceeded, if the data was pushed by the remote, or if the remote closed. The 
completionCode indicates the status of the completed get call. 

waitForUrgent watches for a packet to arrive with the urgent bit set. This procedure 
returns as soon as TCP receives a packet with the urgent bit set. It is then the client’s 
responsibility to issue gets to flush the stream to the end of the urgent data. Typically, a 
client has a separate process that is waiting in waitForUrgent and it notifies the data 
receiver when it receives notification of pending urgent data. As with all operations that 
block, waitForUrgent can be cancelled. 

close is the operation used to start gracefully closing down the stream when the client has 
no more data to send. Outstanding puts are transmitted until complete, as flow control 
permits. After calling this procedure, the client should issue gets to receive outstanding 
data until a get returns with the completion code of closed, indicating the remote end has 
also issued a close. It is the client’s responsibility to continue the ’’graceful” close 
handshake by retrieving the close outcome from the remote with get. If the client destroys 
the stream immediately after issuing a close, without waiting for the close from the other 
end, the data will not be reliably transferred. 

setWaitTime sets the current timeout value for the stream. The timout is the amount of 
time in milliseconds that a get waits for the requested data before returning to the client. 

find Addresses returns the sockets that identify the connection. 


11.2.3 Restrictions 

The options parameter in the Make procedure is currently ignored. Since only the 
maximum segment size option exists, and it is set by TCP during the connection 
handshake. 

Precedence and security are ignored, both in incoming segments and as parameters passed 
by the client. The precedence currently used by all connections is routine. The security is 
unclassified. 
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11.2.4 References 

RFC793 Transmission Control Protocol, Postel, September, 1981. 

An RFC can be copied from the < RFC > directory at SRI’s machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.3 ArpaAddressTranslation 

The ArpaAddressTranslation interface translates strings into the internal represention of 
internet addresses and translates the internal represention of internet addresses into 
human readable strings. 

11.3.1 Errors 

Error: ERROR [errorRecord: ErrorRecord]; 

ErrorRecord: TYPE = RECORD [ 

SELECT errorType: ErrorType FROM 

scanError » > [position: CARDINAL], 
badSyntax ■ > [field: Field], 
nameLookupProblem ■ > [rc: ReturnCode], 

ENDCASE]; 

Field: TYPE ■ (octetl, octet2, octet3, octet4, ambiguous}; 

ErrorType: TYPE = {scanError, badSyntax, nameLookupProblem}; 
scanError 

The string passed is not in the proper format and cannot be parsed. The position field gives 
the location of the parse error. 

badSyntax 

The address resulting from the string passed is invalid. The field field gives the field in 
which the error occured. 

nameLookupProblem 

The name could not be found. The rc field gives the reason the name could not be found. 

ReturnCode: TYPE ■ {cantAcquireHstTxt, noSuchName}; 

cantAcquireHstTxt The host table file (HOSTS.TXT) cannot be acquired. 


noSuchName 


The name cannot be found in table. 
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11.3.2 Procedures 

StringToInternetAddress: PROCEDURE [ 
s: LONG STRING] 

RETURNS [addr: ArpaRouter.InternetAddress]; 

This procedure parses the string passed and returns the corresponding internet address. If 
the string passed is a numeric string, the conversion is done directly. If it is 
alphanumeric, the string is looked up in the host table, HOSTS.TXT, and the address in 
the host table is returned. This procedure can raise the error Error. 

• The following bases are understood: octal, decimal and hexadecimal. 

• All fields are first assumed to be decimal. The assumption holds as long as the 
characters are in the range [0..9] and the last character of a field is not *b or *B or 'h or 
f H. 

• If the character *b or *B is the last character of a field and the field only contains 
characters in the range [0..7], then the field is assumed to be octal. 

• If a character in the range [A..F] is encountered, the field is assumed to be 
hexadecimal. 

• If any character is encountered in any field that is outside of the above specification, 
the whole string is treated as a name and is compared to host table entries in 
HOSTS.TXT. 

InternetAddressToString: PROCEDURE [ 

addr: ArpaRouter.InternetAddress, s: LONG STRING, radix: CARDINAL TO]; 

This procdure takes an ArpaRouter.InternetAddress and converts it to the standard 
host number representation (four eight bit numbers seperated by decimals points) If the 
radix is 8 then the character B is appended to each number. If the radix is 10 the character 
D is appended to each number. If the radix field is set to 0 all numbers are in base ten 
without the D appended. The string passed must be large enough to accomodate the 
result, otherwise String errors may be raised. 

11.3.2.1 Host table 

The host table is assumed to be in the file HOSTS.TXT and to have the syntax specified by 
RFC952 except for the following three special entries. MY-HOST is used to give the local 
machines host address, MY-GATEWAY is used to specify the local machines gateway, and 
SUBNET-MASK gives subnet masking bits if the machine is on a subnet. These entries 
have the following syntax: 

entry := < keyword > < address > 

keyword : = MY-HOST | MY-GATEWAY | SUBNET-MASK 

address : = octetoctetoctetoctet 

octet: = < 0 to 255 decimal > 
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11.3*3 References 

RFC952 DoD Internet Host Table Specification, Harrrenstien, October , 1985. 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.4 ArpaAddressCache 

The interface ArpaAddressCache provides Pilot clients with direct access to the the local 
cache of Internet addresses. Calls to this interface may result in the loading of this cached 
information if the information does not currently exist in the cache. Currently, cache 
information is kept in the file HOSTS.TXT. See RFC952 for a description of this file. 

11.4.1 Procedures 

AddEntry: PROC[ 

name: LONG STRING, addr: ArpaRouter.InternetAddress]; 

This procedure adds an entry into the cache table. The name string should contain the 
name of the host to be added and the addr field should contain the Internet address of the 
host. The name string should be in the format specifed by RFC952. 

Enumerate: PROC[ 
proc: PROC[ 

name: LONG STRING, 

addr: ArpaRouter.InternetAddress]]; 

The Enumerate procedure calls the call back procedure proc for the name and addr of 
every entry in the cache. 

Flush: PROC; 

The Flush procedure flushes all entries from the cache. 

Lookup: PROClname: LONG STRING] 

RETURNS[ 

addr: ArpaRouter.InternetAddress, hit: BOOLEAN]; 

The Lookup procedure finds the specifed name in the cache table. If the cache has not 
been loaded, it will be loaded. If the entry is not found, the hit field is set to FALSE. If the 
entry is found, it is returned in the field addr. This procedure may raise the error 
ArpaAddressTranslation.Error when the file HOSTS.TXT cannot be found on the local file 
system. 

LookupAddr: PROCEDURE [ 

addr: ArpaRouter.InternetAddress] 

RETURNS [name: LONG STRING]; 
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The LookupAddr procedure finds the speeifed addr in the cache table and returns the 
corresponding name for that addr. If the cache has not been loaded the cache, it is loaded. 
If the entry is not found the name field is set to NIL. This procedure may raise the error 
ArpaAddressTranslation.Error when the file HOSTS.TXT cannot be found on the local file 
system. 

11.4.2 References 

RFC952DOD Internet Host Table Specification , Harrenstien , October , 1985 . 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.5 ArpaHostTable 

The ArpaHostTable interface provides Pilot clients with an interface to a parser that 
parses files in the format specified by RFC952, 

11.5.1 Procedures 

ParseHostsFile: PROCEDURE [ 

fileName: LONG STRING] RETURNS [success: BOOLEAN]; 

The procedure ParseHostsFile parses files in the format specified by RFC952. The field 
fileName is a string of the filename of the file to be parsed. The field success returns TRU E 
if the file parse returned successfully. Currently only the HOST fields of the file being 
parsed are understood. These entries are cached using the ArpaAddressCache interface 
and can be accessed using the ArpaAddressTranslation interface. 

GetArpalnitlnfo: PROCEDURE RETURNS [ 

hostAddr, gateWayAddr, subnetMask: ArpaRouter.InternetAddress]; 

To accomodate a need to acquire the Internet address of the local processor, the address of 
the nearest gateway, and the subnet masking information, three unique entries must be 
included in the default hosts file (HOSTS.TXT). These entries are MY-GATEWAY, MY- 
HOST, and SUBNET-MASK. MY-HOST is used to give the local machine’s host address, MY- 
GATEWAY is used to give the local machine’s initial gateway, and SUBNET-MASK is used 
to get the subnet bits for address comparisions if the machine is on a subnet. These 
entries have the following syntax: 

entry := <keyword> <address > 

keyword : = MY-HOST | MY-GATEWAY | SUBNET-MASK 

address : = octet octet octet octet 

octet := < 0 to 255 decimal > 

These entries must be of the same address class. These values are returned by this 
procedure in the fields hostAddr, gateWayAddr, and subnetMask. 
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11.5.2 References 

RFC952 DOD Internet Host Table Specification, Harrenstien, October, 1985. 

An RFC can be copied from the < RFC > directory at SRI’s machine: 

SRI • NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.6 ArpaTelnetStream 

The ArpaTelnetStream interface provides Pilot clients with an interface to the Telnet 
Protocol defined by RFC854 and Telnet options defined by RFCs 855 to 861. Telnet is a 
virtual terminal protocol to be used with the TCP/IP protocols. 

11.6.1 Types and constants 

Handle: TYPE « LONG POINTER TO Object; 

Object: TYPE = RECORD [ 
options: Options, 
getByte: PROCEDURE [sH: Handle] 

RETURNS [byte: Environment.Byte, code: ReturnRecord], 
putByte: PROCEDURE [ 

sH: Handle, byte: Environment.Byte, push: BOOLEAN], 
get: PROCEDURE [sH: Handle, block: Environment.Block] 

RETURNS[bytesTransferred: CARDINAL, code: ReturnRecord], 
put: PROCEDURE [ 

sH: Handle, block: Environment.Block, push: BOOLEAN], 
push: PROCEDURE [sH: Handle], 
delete: PROCEDURE [sH: Handle], 
dientData: UserDataEntry, 
getTimeout: PROCEDURE [sH: Handle] 

RETURNS [timeOut: TcpStream.WaitTime], 
setTimeout: PROCEDURE [ 

sH: Handle,timeOut: TcpStream.WaitTime], 
setlnputOptions: PROCEDURE [sH: Handle, options: Options], 
flushDataLine: PROCEDURE [sH: Handle]]; 

A telnet Handle is modeled after the pilot stream handle interface and the procedures it 
contains are similar to the pilot stream interface. 

The options record contains settings of a variety of user parameters. 

The getByte procedure returns the next byte of data in the data stream. If there is no data 
pending, it waits for an infinite amount of time if no time out was set or the amount of 
time specified in the setTimeout procedure. getByte also returns the reason that the 
procedure is returning in the field code. In most cases this is set to normal, but if some 
event occurs that forces the procedure to return, this is noted in the code field. 
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The putByte procedure places one byte of data on the out going Telnet connection. Setting 
the push flag to TRU E has the same effect as the sendNow procedure on a pilot stream: the 
data is flushed from the sending side to the receiving side. If the push flag is TRUE, the 
TCP data buffers are flushed. This is an expensive operation and should be done only 
when necessary. 

The get and put procedures are similar to the getbyte and putByte procedures except they 
operate on blocks rather than bytes. The same comments on the push boolean apply for 
put as did for putByte. 

The push procedure causes all buffered data to be sent to the telnet partner. This is the 
same operation that is done when put or pupByte procedures are called with the push 
boolean set to TRUE. 

The clientData field is a pointer to data needed by the internal implementation. 

The getTimeout procedure returns the timeout that is set on the telnet connection. 

The setTimeout procedure is used to set the amount of time the telnet connection waits on 
a get operation before returning with a timeout reason or before raising the timeout 
signal. If this procedure is called with a value of 0, then the timeout in effect is infinite. 
The length of time the get process can wait is limited to about 16 minutes. 

The procedure setlnputOptions is used to set various options described below. 

The flushDataLine procedure flushes the incoming data stream of all pending data. 

UserDataEntry: TYPE[2]; 

Opaque type used by telnet internal implementation. 

Options: TYPE * RECORD [ 

signalTimeOut: BOOLEAN TRUE, 
signalOnGoAhead: BOOLEAN FALSE, 

signalOnEraseLine: BOOLEAN FALSE, 

signalOnEraseChar: BOOLEAN <- FALSE, 
signalOnAbort: BOOLEAN FALSE, 
signalOnlnterrupt: BOOLEAN FALSE, 
signalOnBreak: BOOLEAN «- FALSE, 
signalOnShortBlock: BOOLEAN FALSE, 
willEcho: BOOLEAN TRUE, 
willBinary: BOOLEAN TRUE, 
willStatus: BOOLEAN <— TRUE]; 

Options decide the way in which the Telnet connection operates and how the client is 
notified about connection events. The options that decide how the user is notified about 
telnet events are signalTimeOut, signalOnGoAhead, signalOnEraseLine, 
signalOnEraseChar, signalOnAbort, signalOnlnterrupt, signalOnBreak and 
signalOnShortBlock. The options which govern the way a telnet connection responds to 
option requests from a connection partner are willEcho, willBinary and willStatus. The 
signal options, when true, cause the client to be signaled rather than notified in the return 
arguments of the get call of an event that has taken place. These events are described 
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below. The other options govern the telnet options exported to Telnet users, will Echo 
allows the telnet partner to request remote echo rather than always having to do local 
echo. willBinary allows the telnet partner to request a binary transmission path rather 
than using the NVT (Network Virtual Terminal) character code standard. willStatus 
allows the telnet partner to request its partners status information. 

ReturnCode: TYPE ■ {normal, timeOut, goAhead, eraseLine, eraseChar, abort, interrupt, 
break, shortBlock, echo, binary, endOfRecord, terminalType, status}; 

ReturnRecord: TYPE = RECORD [ 

returnCode: ReturnCode normal, 
argument: SELECT OVERLAID ReturnCode FROM 
timeOut * > [index: CARDINAL 0] 
binary, echo = > [on: BOOLEAN «- FALSE], 
terminalType ■ > [string: LONG STRING], 
status » > [hostStatus: HostStatusRecord], 

ENDCASE]; 

The ReturnRecord is returned by all get operations dealing with data. The following is a 
description of each return code. 

normal - The procedure is returning because it has exhausted the space provided for the 
results of the get operation. 

timeOut - The get procedure has taken longer than the specified time set with the 
setTimeout procedure. In the variant part of the return record the index points at the last 
byte of data received. 

goAhead - When the goAhead code is returned, the telnet partner indicates that all the 
data has been sent and it is now waiting for data. 

eraseLine - The remote side of the telnet connection has sent an erase line code. The user 
should treat this as if an eraseLine character were typed to the local stream. 

eraseChar - The remote side of the telnet connection has sent an erase character code, the 
user should treat this as if an eraseChar character were typed to the local stream. 

abort - The remote side of the telnet connection indicated that all the queued output 
should be suspended but that the currently running process should continue. 

interrupt - The remote side of the telnet connection indicated that the current process 
should be cancelled. 

break - Same as pressing the Break key (128 decimal). 
shortBlock - Not used. 

echo - The remote side of the telnet connection has requested echoing from the server side. 

binary -The remote side of the telnet connection indicated that data transmitted should be 
treated as binary data without regard for the NVT character set. 
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endOfRecord- Not used. 

terminalType - The return record contains the terminal type requested. The terminal type 
is an Ascii string and should conform to RFC 940 - Assigned Numbers. 

status - This is the return of an earlier status request. The status information is contained 
in the return record. 

HostStatusRecord: TYPE ■ RECORD [ 
optionsPossible: 

PACKED ARRAY OptionsEnnum OF BOOLEAN <- ALLfTRUE], 
optionsRecord: 

PACKED ARRAY OptionsEnnum OF BOOLEAN 4- ALL[FALSE], 
optionsVerified: 

PACKED ARRAY OptionsEnnum OF BOOLEAN ALL[FALSE] # 

Terminal: LONG STRING]; 

The HostStatusRecord is returned when the user requests the status of the Telnet 
connection. The fields should be interpreted as follows: the optionsPossible field are 
those options which the telnet connection partner may export, the optionsRecord are 
those options which are enabled at the connection partner site, and the optionsVerified 
field is the list of those options which the connection partner supports. The above fields 
can be indexed using the OptionsEnnum enumeration which lists all the options 
supported by this implementation of Telnet. The Terminal is an Ascii string specifying the 
terminal type which the connection is supporting. This field may be NIL if no terminal 
type is set. 

OptionsEnnum: TYPE ■ {Binary, Echo, SupGA, Status, TimeMark, TerminalType, EOR, 
ExtendedOptionsList}; 

The OptionsEnnum is an ennumeration of all the supported telnet options. 

Binary - Indicates binary transmission of data characters, not using NVT. 

Echo - If the echo field is TRUE, the site supports or is doing echo rather than the local site 
echoing typed characters. 

SupGA - Indicates the suppression of GoAhead characters. 

Status - Indicates the transmission of status information. 

TimeMark - Indicates Telnet Timing Mark option. 

TerminalType - Indicates the support of other terminal types other that the standard NVT 
(Network Virtual Terminal) 

EOR - Indicates support of the end-of-record option. 

ExtendedOptionsList - This option is not supported. 
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11.6.2 Signals 

Error: SIGNAL [reason: TelnetErrorReason]; 

TelnetErrorReason: TYPE ■ {doesntBinary, doesntEcho, doesntStatus, doesntTermType, 
timeOut}; 

The SIGNAL Error is raised either when the client trys to enable an option that is not 
supported by the Telnet connection or when the timeout interval set by the client is 
reached on a get operation. 


11.6.3 Procedures 

Create: PROCEDURE [ 

input: TcpStream.Handle, 
options: Options, 
addLFToCR: BOOLEAN TRUE] 

RETURNS [telnetStream: Handle]; 

Create sets up a stream-like connection to a remote host. The parameters needed are a 
TcpStream.Handle to the connection which provide the data in the field input, the set of 
options which describe how the telnet stream appears to the user, as well as the telnet 
connection partner, and the the boolean addLFToCR, which defaults to TRUE if not 
supplied. This boolean should be set FALSE when the client wishes to provide lines ending 
only in a Ascii carriage return. The Telnet implementation adds the additional Ascii line 
feed (LF) to make the line a valid Telnet line. This procedure returns a Handle which 
contains the procedures which are the telnet stream. 

GetByte: PROCEDURE [sH: Handle] 

RETURNS [byte: Environment-Byte, code: Return Record]; 

The GetByte procedure returns the next byte of data in the data stream. If there is no data 
pending, it waits the amount of time set in the SetTimeout procedure, or an infinite 
amount of time if no time out was set. GetByte also returns the reason that the procedure 
is returning. In most cases, this will be set to normal, but if some event occurs that forces 
the procedure to return, this is noted in the code field. 

PutByte: PROCEDURE [ 

sH: Handle, byte: Environment.Byte, push: BOOLEAN] ■ 

INLINE {sH.putByte[sH, byte, push]}; 

The PutByte procedure places one byte of data on the out-going Telnet connection. Setting 
the push flag to TRUE has the same effect as the sendNow procedure on a pilot stream and 
the data is flushed from the sending side to the receiving side. The push flag generates a 
TCP Push flag. This is an expensive operation and should be done only when neccesary. 

GetBlock: PROCEDURE [sH: Handle, block: Environment.Block] 

RETURNS [bytesTransferred: CARDINAL, code: ReturnRecord]; 
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PutBlock: PROCEDURE [ 

sH: Handle, block: Environment.Block, push: BOOLEAN] ■ 

INLINE {sH.putfsH, block, push]}; 

The GetBlock and PutBlock procedures are similar to the GetByte and PutByte procedures 
except they operate on blocks rather than bytes. The same comments on the push boolean 
apply for PutBlock as did for PutByte. 

Push: PROCEDURE [sH: Handle] * INLINE {sH.push[sH]}; 

The Push procedure will cause all buffered data to be sent to the telnet partner. This is the 
same operation that is done when PutBlock or PutByte is called with the push boolean set 
to TRUE. 

GetTimeout: PROCEDURE [sH: Handle] 

RETURNS [timeOut: TcpStream.WaitTime] ■ 

INLINE {RETURN[sH.getTimeout[sH]]}; 

The GetTimeout procedure returns the timeout that is set on the telnet connection. 

SetTimeout: PROCEDURE [ 

sH: Handle,timeOut: TcpStream.WaitTime] = 

INLINE {sH.setTimeout[sH, timeOut]}; 

The SetTimeout procedure is used to set the amount of time the telnet connection waits on 
a get operation before returning with a timeout reason or raising the timeout signal. If 
this procedure is called with a value of 0, then the timeout in effect is infinite. The length 
of time the get process can wait is limited to about 16 minutes. 

SetlnputOptions: PROCEDURE [sH: Handle, options: Options] * 

INLINE {sH.setlnputOptions[sH, options]}; 

The procedure SetlnputOptions is used to set various options described above. 

Delete: PROCEDURE [sH: Handle] * INLINE {sH.deletefsH]}; 

Delete is called before closing the Telnet connection to free up local storage and destroy 
the Handle passed in by the Create procedure. 

FlushDataLine: PROCEDURE [sH: Handle] » 

INLINE {sH.flushDataLine[sH]}; 

The FlushDataLine procedure flushes the incoming data stream of all pending data. 

GA: PROCEDURE [sH: Handle]; 

The GA procedure sends the go ahead signal on the telnet connection. 

AbortOutput: PROCEDURE [sH: Handle]; 

This procedure cancels the output of a remote process if the connected system supports 
output abort, otherwise the process continues to completion. 
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JnterruptProcess: PROCEDURE [sH: Handle]; 

This procedure interrupts a remote process if the connected system can interrupt the 
process. 

AreYouThere: PROCEDURE [sH: Handle]; 

This procedure forces the remote host to send some visible signal (character or string) that 
the connection is still active. The character or string is seen on the get operation. 

EraseLine: PROCEDURE [sH: Handle]; 

This procedure erases the last line typed (to the last CRLF). 

EraseChar: PROCEDURE [sH: Handle]; 

EraseChar is used instead of BS SP to do an erase of the last character. On many systems 
the character BS does the correct operation. 

The following procedures all may raise the Error signal if that option is not supported by 
the remote site. 

Echo: PROCEDURE [sH: Handle, on: BOOLEAN]; 

Echo causes the remote connection to echo characters rather than having the local 
connection echo characters. Described by RFC 857. 

Binary: PROCEDURE [sH: Handle, on: BOOLEAN]; 

Binary causes the connection to stop interpreting characters as NVT characters. This is 
described by RFC 856. 

Break: PROCEDURE [sH: Handle]; 

This procedure sends the Telnet break character to the remote host. 

Status: PROCEDURE [sH: Handle] 

RETURNS [status: LONG POINTER TO HostStatusRecord]; 

Status causes the remote site to send connection status information if this option is 
supported. This is described by RFC 859. 

SetTerminalType: PROCEDURE [ 

sH: Handle, terminalType: LONG STRING] 

RETURNS [success: BOOLEAN]; 

Sends the terminal type requested to the remote site if the terminal type option is 
supported. See RFC 943 Assigned Numbers under the Terminal Types heading for a list of 
valid terminal type strings. This procedure uses telnet subnegotiation to negotiate the 
terminal type with the remote host. The default is NVT. 
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11.6.4 References 

RFC854 TELNET Protocol Specification , Postel , May y 1983. 

RFC855 TELNET Option Specification , Postel , May , 1983. 

RFC856 TELNET Binary Transmission , Postel , May, 1983. 

RFC857 TELNET Echo Option , Postel , May, 1983. 

RFC858 TELNET Suppress Go Ahead Option , Postel , May, 1983. 

RFC859 TELNET Status Option , Postel , May, 1983. 

RFC860 TELNET Timing MarkOption, Postel , May, 1983. 

RFC861 TELNET Extended Options - List , Postel , May, 1983. 

RFC960 Assigned Numbers , Reynolds , December , 1985. 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.7 TelnetListener 

The TelnetListener interface provides Pilot clients with an interface to the Telnet Protocol 
defined by RFC854. The TelnetListener interface is used by clients needing to listen on a 
specified port for a telnet connection. Telnet is a virtual terminal protocol used with the 
TCP/IP protocols. 

11.7.1 Types and constants 

ConnectProc: TYPE » PROCEDURE [ 
sH: ArpaTelnetStream.Handle, 
underlyingStream: TcpStream.Handle, 
remoteAddr: ArpaRouter.InternetAddress]; 

The procedure type ConnectProc is called by the telnet interface when a connection is 
received on the port specified in the Listen procedure. 

ConnectID: TYPE [2]; 

This ID is returned by the Listen procedure and is used to destroy a Telnet listening 
connection. 
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11.7.2 Procedures 

Listen: PROCEDURE [ 
connect: ConnectProc, 
portNumber: ArpaRouter.Port, 
suppressLF: BOOLEAN *- FALSE] 

RETURNS [connectionID: ConnectID]; 

The Listen procedure is called by the client to establish a telnet listening connection on the 
port specified in the field portNumber. The procedure called when a connection is received 
is passed in the field connect. If line feeds are to be suppressed every time a carriage 
return is seen (CRLF -* CR), the suppressLF boolean should be set to TRUE. This procedure 
returns the value connectionID to be used in destroying the telnet listener. 

StopListening: PROCEDURE [connectionID: ConnectID]; 

This procedure destroys a listening connection started with the procedure Listen. 
StopListening is called with the connectionID returned by Listen. 

11.7.3 References 

RFC854 TELNET Protocol Specification, Postel, May, 1983. 

An RFC can be copied from the <RFC > directory at SRI’s machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.8 ArpaFilingCommon 

The ArpaFilingCommon interface provides types to be used by clients using the TFTP or 
ArpaFTP interfaces. It defines a set of common types so that these types can be used with 
both the TFTP and ArpaFTP interfaces. 

11.8.1 Types and constants 
StatusCode: TYPE > { 

ok, notRetrieving, notStoring, fileNotFound, accessViolation, mediumFull, fileExists, 
invalidFileName, undefined, eof}; 

The StatusCode type is used to return information about the state of the local filing 
operation in a standard manner. 

ok The filing action completed successfully. 

notRetrieving The filing action did not complete because file retrieval is 

not allowed by the local filing system. 


11-20 



Pilot Programmer’s Manual 


11 


notStoring 


The filing action did not complete because file storing is not 
allowed by the local filing system. 


fileNotFound 


The file action did not complete because the specified file 
was not found in the current context. 


accessViolation 


mediumFull 


fileExists 


The user did not have sufficient access rights to access the 
file or the file is in use by another user. 

The file storing action did not complete because the local 
filing medium is full or the user has exhausted the allocated 
space. 

The file being accessed exists but could not be overwritten. 


invalidFileName 


The specified file name is not valid in the current context. 


undefined 


A file error that doesn’t fit into the above catagories. 


eof 


The logical end of the file was reached successfully and 
there is no more data to retrieve. 


PutProc: TYPE = PROCEDURE [ 
fileStream: Stream.Handle, 
block: Environment.Block, 
eot: BOOLEAN FALSE] 

RETURNS [statusCode: StatusCode]; 

The PutProc type is used as the call back procedure to a file storing operation. The field 
fileStream contains a stream to the currently active local file and is passed to the caller 
using some other protocol specific operation. The field block contains the data to be stored. 
The field eot is set true when the file transfer has ended. The field statusCode is returned 
with a code. 

GetProc: TYPE = PROCEDURE [ 

fileStream: Stream.Handle, block: Environment.Block] 

RETURNS [statusCode: StatusCode, 
bytesTransferred: CARDINAL]; 

The GetProc type is used as the call back procedure to a file retrieval operation. The field 
fileStream contains a stream to the currently active local file and is passed to the caller 
using some other protocol specific operation. The field block receives the data to be sent. 
The field statusCode is returned with a code and the number of bytes transmitted is in the 
field bytesTransferred. 

CloseProc: TYPE * PROCEDURE [ 
fileStream: Stream.Handle, 
deleteFile: BOOLEAN 4- FALSE, 
fileName: LONG STRING NIL]; 

The type CloseProc is used a call back procedure in either a file retrieval or file storing 
operation. It is called when the operation has completed. The field fileStream contains a 
stream to the specifed local file that was passed to the caller by some protocol specific 
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operation. The deleteFile field, when TRUE and the file operation is storing, indicates 
that the file operation did not complete and that the file stored may be incomplete and 
should be deleted. The field fileName contains the name of the file when the field 
deleteFile is TRUE and may provide a hint as to which file should be deleted. 

PrintProc: TYPE a PROCEDURE 
[stringToPrint: LONG STRING]; 

The type PrintProc is used by the caller to notify the client of debugging information. 


11.9 TFTP 


Trivial File Transfer Protocol (TFTP) is a simple file transfer protocol which is a client of 
the User Datagram Protocol (UDP). It can be used to tranfer files between hosts 
implementing the arpa protocols. See RFC783 for a full description of this protocol. 

11.9.1 Types and constants 

TFTPModes: TYPE a {netascii, octet, mail}; 

TFTPModes is used to indicate the type of file being transferred. 

netascii This is Ascii as defined in USA Standard Code for Information 

Interchange with modifications specified in RFC764 . It is eight-bit ascii. 

octet Raw eight-bit bytes. 

mail Netascii characters sent to a user rather than a file. 

FileStreamProc: TYPE a PROCEDURE [ 

fileName: LONG STRING,fileType: TFTPModes] 

RETURNS[ 

statusCode: ArpaFilingCommon.StatusCode, 
fileStream: Stream.Handle, put: ArpaFilingCommon.PutProc, 
get: ArpaFilingCommon.GetProc, 
doseProc: ArpaFilingCommon.CloseProc]; 

The FileStreamProc procedure is used by the server side of an TFTP connection to solicit 
information from the TFTP server client. The put and get callback procedures are used to 
store or retrieve file data from the client's file system. The close procedure is called when 
the file transfer is completed. For the store case, the get procedure need not be provided 
and for the retrieve case, the put procedure need not be provided. When the 
FileStreamProc is called, file type information is derived from the fileType field and the 
file name from the fileName field. Client filing errors are returned using the statusCode 
field. 

GetStreamProc: TYPE * PROCEDURE [fileName: LONG STRING] 

RETURNS [stream: Stream.Handle, fileError: BOOLEAN]; 

This is used by Retrieve for file stream creation. 
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11*9.2 Errors and signals 

TFTPError: ERROR [reason: TFTPErrorReason, errorMsg: LONG STRING]; 

TFTPErrorReason: TYPE * {aborted, undefined, fileNotFound, accessViolation, 
mediumFull, illegalOp, unknownTID, fileExists, noSuchUser, timeOut, hostError, 
localFileError}; 

aborted The current session is cancelled, 

undefined Not defined, error message may help. 

fileNotFound File was not found at the remote location. 

accessViolation The remote file cannot be accessed. 

mediumFull The remote sites disk is full or allocation exceeded. 

illegalOp Received an illegal TFTP responce. 

unknownTID Not used. 

fileExists File exists and cannot be overwritten. 

noSuchUser Not used. 

timeOut The TFTP session has timed out becuase the remote site has 

not responded. 

hostError Remote error. 

localFileError Error in acquiring the file for transmission. 

The errorMsg is passed by the protocol and contains an English error message. The 
errorMsg is allocated from the zone passed into the interface by the client and should be 
freed by the client. 

11.9.3 Procedures 

Send: PROCEDURE! 

toHost: ArpaRouter.InternetAddress, 
fileName: LONG STRING, 
fileStream: Stream.Handle, 
dataProc: ArpaFilingCommon.GetProc, 
zone: UNCOUNTED ZONE, 
rexmt: CARDINAL 4- 5, 
timeOut: CARDINAL 4- 25]; 

Send is used to store a file to a TFTP server. The toHost field has the address of the 
destination file. The fileName field has the name of the file on the remote server and 
should be in the file naming structure of the remote machine. fileStream is a stream to the 
local file to be stored. The callback procedure provided in dataProc is used to retrieve the 
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file from the local file system. This procedure may raise TFTPError {... aborted, 
undefined, accessVioIation, mediumFull, illegalOp, fileExrsts, timeOut...}. Any error 
message strings returned by the signal TFTPError are allocated from zone and should be 
freed by the client. The rexmt field gives the timeout between TFTP data packets and 
TFTP acknowledgements. The field timeOut gives the total timeout period for the TFTP 
connection. 

Retrieve: PROCEDURE [ 

fromHost: ArpaRouter.InternetAddress, 
fileName, locaiName: LONG STRING, 
fileType: TFTPModes, 
fileStreamProc: GetStreamProc, 
zone: UNCOUNTED ZONE, 
rexmt: CARDINAL 5, 
timeOut: CARDINAL 25]; 

The Retrieve procedure is used to retrieve a file from a TFTP server. The fromHost field 
has the address of the source of the file being retrieved. The fileName field has the name 
of the file on the remote server and should be in the file naming structure of the remote 
machine. The fileStreamProc is called when a connection is established to acquire the 
local filing stream handle. If a local filing error is encountered when trying to acquire the 
local file, the fileStreamProc should return a NIL stream handle and a value of TRUE in 
the fileError field. Retrieve may raise TFTPError {... Aborted, Undefined, FileNotFound, 
AccessVioIation, IllegalOp, TimeOut...}, Any error message strings returned by the signal 
TFTPError are allocated from zone and should be freed by the client. The rexmt field gives 
the timeout between TFTP data packets and TFTP acknowledgements. The field timeOut 
give the total timeout period for the TFTP connection. 

Register: PROCEDURE [ 

storeFile: FileStreamProc, 
retrieveFile: FileStreamProc, 
print: PrintProc, 
zone: UNCOUNTED ZONE, 
rexmt: CARDINAL 5, 
timeOut: CARDINAL 25]; 

Register is used for server side filing implementation. The procedures registered are 
called in the following instances. StoreFile is called when a request to write is received by 
the server. RetrieveFile is called when a request to read is received by the server. The 
print procedure is used for debug and status messages. The rexmt field gives the timeout 
between TFTP data packets and TFTP acknowledgements. The field timeOut gives the 
total timeout period for the TFTP connection. Only one client should register procedures. 
Other clients who register procedures overwrite the previous procedures. 

UnRegister: PROCEDURE; 

This procedure is called to suspend TFTP server operations. 

11.9.4 References 

RFC764 Telnet Protocol, Postel , June, 1980 . 
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RFC783 The TFTP Protocol (Revision 2), Sollins,June, 1981. 

An RFC can be copied from the < RFC > directory at SRFs machine: 

- NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.10 ArpaFTP 

The ArpaFTP interface provides Pilot clients with an interface to the File Transfer 
Protocol (FTP) defined by RFC959. FTP is a file transfer protocol used in with the TCP/IP 
protocols. 

11.10.1 Types and constants 

Handle: TYPE * LONG POINTER TO FTPObject; 

FTPObject: TYPE; 

FileTypeEnum: TYPE ■ {ascii, EBCDIC, image, other}; 

The FileTypeEnum defines the file types understood by FTP. 


ascii 

This is the default file type, intended for transferring text files. 
Ascii is defined in the Telnet specification to be the lower half of an 
eight-bit code set (the most significant bit is zero). 

EBCDIC 

This type is not supported 

image 

This type is used for the transfer of binary or compressed data. 

other 

This type is used to accomodate other data representations and is 
supported for eight-bit bytes. 

FileFormatEnum: TYPE 

1 * {nonPrint, telnet,asa}; 


The FileFormatEnum defines the set of format control options that can be used with the file 

types Ascii and EBCDIC. 

nonPrint This is the default formatting option and indicates there is no formatting 

in the file. 

telnet This indicates that the file contains vertical format controls (such as 

>CR>, <LF>, <NL>, <VT>, <FF>). 

asa This indicates that the file contain asa (FORTRAN) vertical control 

characters. (See RFC 740 or Communications of the ACM, Vol. 7, No. 10, 
p. 606, October 1964). 

FileStructureEnum: TYPE ■ {file, record, page}; 
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The FileStructureEnum defines the set of file structures that are know to FTP, 

file This is the defaulted file structure. 

record This is not supported. 

page This is not supported. 

TransmissionModeEnum: TYPE = 

{stream, block, compressed}; 

The TransmissionModeEnum defines the set of data transmission types known to FTP. 

stream This is the default transmission mode. The data is transmitted as a 

stream of bytes. 

block This is not supported. 

compressed This is not supported. 

Options: TYPE = RECORD [ 

fileType: FileTypeEnum f-ascii, 
fileFormat: FileFormatEnum nonPrint, 
fileByteSize: CARDINAL 4-8, 
fileStructure: FileStructureEnum <— file, 
transmissionMode: TransmissionModeEnum <- stream, 
modeChanged: BOOLEAN <- FALSE, 
fileTypeChanged: BOOLEAN FALSE, 
fileStructureChanged: BOOLEAN 4- FALSE, 
optionsChanged: BOOLEAN FALSE]; 

The options record is used to set various options allowed by the FTP protocol. Not all 
options are available on all hosts. When options are changed the optionschanged field for 
the appropriate option should be set to TRUE (for example, when transmissionMode is 
changed the modeChanged boolean should be set to TRUE) and the optionschanged 
BOOLEAN should be set to TRUE. The fileByteSize is the size of the data bytes of a file. 
Only a byte size of eight is supported. 

defaultOptions: Options ■ [ascii, nonPrint, 8, file, stream]; 

The defaultOptions can be used to set the options field in Store and Retrieve. 

ListStyle: TYPE ■ {verbose, terse}; 

The ListStyle type is used with the List procedure to indicate whether verbose (all 
information that can be displayed about the file) or terse (only the file name) is wanted. 

OutputListProc: TYPE a PROCEDURE [output: Environment.Block]; 

The OutputListProc is used with the List command to provide a call back procedure for the 
listing return information. 
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11.10.2 Errors and Signals 
FTPError: ERROR [ 

reason: FTPErrorReason, errorNumber: CARDINAL, errorstring: LONG STRING]; 

The error FTPError is raised for all error conditions that arise on the local or remote 
machine. The error reasons are described below. The errorNumber field is reserved for 
error conditions that are reported by the remote FTP site. Error numbers follow the error 
number definitions as outlined by RFC 959. The errorstring is also reserved for remote 
errors and is the human readable text message that accompanies the FTP errorNumber. 
The string errorstring is allocated from a private zone and is deallocated on unwinding 
this error. 


FTPErrorReason: TYPE ■ {accessViolation, accountNeeded, badCommandSequence, 
fileExists, fileNotFound, hostError, illegalOp, invalidFileName, invalidOption, 
localFileError, mediumFull, noSuchUser, remoteFileError, serverCommandError, 
serviceUnavailable, timeOut, userNotLoggedln, undefined, unimplemented}; 


accessViolation 

accountNeeded 

badCommandSequence 

fileExists 

fileNotFound 

hostError 

illegalOp 

invalidFileName 

invalidOption 

localFileError 

mediumFull 

noSuchUser 

remoteFileError 

serverCommandError 


User does not have the access right for this operation. 

The user must supply an account number to complete the 
operation. 

The protocol commands were received in the wrong order by 
the remote site. 

The remote file already exists and could not be overwritten 
or deleted. 

The operation indicated could not complete because the file 
was not found. 

Not used. 

Some illegal operation was attempted. 

The file name specified was invalid. 

The options specified were invalid in this context. 

Some local filing error was encountered. 

The remote filing medium is full or the current operation 
exceeds the user's space allocation. 

The user name could not be found on the remote host. 

Some remote file error was encountered. 

The FTP command sent to the remote site could not be 
understood by the remote site. 
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serviceUnavailable The file service is not available at this time. 

timeOut The operation timed out. The remote host may no longer be 

responding. 

userNotLoggedin The user is not be logged in. 

undefined An undefined error was raised by the remite site. 

unimplemented The indicated action is not implemented by the remote host. 

Procedures 
Create: PROCEDURE [ 

destinationHost: ArpaRouter.InternetAddress, options: Options] 

RETURNS [connectionHandle: Handle]; 

Create is used by clients to open an FTP session. The destinationHost is the address of the 
FTP server that is used in the FTP session. The options field is to be filled in according to 
how the connection operates. The connectionHandle returned must be used in all 
subsequent FTP calls for this session. 

Store: PROCEDURE [ 

remoteFileName: LONG STRING, 
fileStream: Stream.Handle, 
getProc: ArpaFilingCommon.GetProc, 
options: Options, 
connectionHandle: Handle]; 

The Store procedure is used to store a file to an FTP server. The remoteFileName field 
should have the name of the file on the remote server, and should be in the file name 
structure of the remote machine. fileStream is a stream to the file to be stored. The 
procedure provided in getProc is used to retrieve the file from the local file system. The 
options field should have the options to be used for this file transfer and should follow the 
conventions stated in the description of the Options record. This procedure may raise the 
error Error. 

Retrieve: PROCEDURE [ 

remoteFileName: LONG STRING, 
fileStream: Stream.Handle, 
putProc: ArpaFilingCommon.PutProc, 
options: Options, 
connectionHandle: Handle]; 

The Retrieve procedure is used to retrieve a file from an FTP server. The remoteFileName 
field should have the name of the file on the remote server, the file name should be in the 
file naming structure of the remote machine. The fileStream field is a stream to the file to 
be stored on the local file system. The procedure provided in putProc is used to retrieve the 
file from the local file system. The options field has the options to be used for this file 
transfer and should follow the conventions stated in the description of the Options record. 
This procedure may raise the error Error. 
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Login: PROCEDURE [ 

userName, userPassword, userAccount: LONG STRING, 
connectionHandle: Handle] 

RETURNS [success: BOOLEAN]; 

The Login procedure sends the given login information to the FTP server. The userName, 
userPassword and userAccount fields should be strings to the users name, password and 
account information on the remote host and should follow the conventions of the remote 
host. Not all values need be specified if not needed on the remote host. The procedure 
returns TRUE if the user has logged in successfully and FALSE if not. This procedure may 
raise the error Error. 

Quit: PROCEDURE [connectionHandle: Handle] 

RETURNS [success: BOOLEAN]; 

The Quit procedure disconnects the user's current filing session from the remote FTP 
server. The FTP connectionHandle is no longer valid after this operation. This procedure 
may raise the error Error. 

List: PROCEDURE [ 

filePathName: LONG STRING, 
outputProc: OutputListProc, 
outputStyle: ListStyle terse, 
connectionHandle: Handle]; 

The List procedure can be used to request that the FTP server send a list of the current 
filing context to the user. The filePathName field specifies a system specific file path 
name. If the outputStyle is verbose, all current information on the file or file group 
specifed by the field filePathName is returned using the procedure outputProc. If the 
outputStyle is terse, only the file name of each of the files specified by the filePathName is 
returned. In either case the file information should be separated by a CRLF or Null 
character. The outputProc sends the received information to the client process. This 
procedure may raise the error Error. 

Delete: PROCEDURE [ 

filePathName: LONG STRING, 
connectionHandle: Handle]; 

The Delete procedure deletes the file defined by the filePathName on the remote FTP 
server. This procedure may raise the error Error. 

Rename: PROCEDURE [ 

from, to: LONG STRING, connectionHandle: Handle]; 

The Rename procedure renames the remote file defined in the from field to the remote file 
name defined in the to field. This procedure may raise the error Error. 

Relnit: PROCEDURE [connectionHandle: Handle]; 

The procedure Relnit reinitializes the current FTP connection specifed by the argument 
connectionHandle. All previous connection states are lost. This procedure is used to 
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change the FTP user without dropping the FTP connection. This procedure may raise the 
error Error. 

Abort: PROCEDURE [connectionHandle: Handle]; 

The procedure Abort cancels any outstanding FTP command on the connection specifed by 
connectionHandle. Any outstanding data transfers terminate. This procedure may raise 
the error Error. 

11.10.4 References 

RFC959 File Transfer Protocol, Postel , October , 1985. 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.11 ArpaFTPServer 

The ArpaFTPServer interface provides Pilot clients with an interface to the server side of 
the File Transfer Protocol (FTP) defined by RFC959. FTP is a file transfer protocol which 
is a client of the TCP/IP protocols (RFC793 and RFC792). 

11.11.1 Types and constants 

Options: TYPE a RECORD [ 

fileType: FileTypeEnum *- ascii, 
fileFormat: FileFormatEnum *- nonPrint, 
fileByteSize: CARDINAL*-8, 
fileStructure: FileStructureEnum 4-file]; 

The Options type defines the record passed to the client to indicate the method a file is 
retrieved or stored. The fileByteSize is the logical byte size of the file transferred. All files 
are transferred as eight-bit files regardless of their logical byte size. 

FileTypeEnum: TYPE ■ (ascii, EBCDIC, image, other}; 

The FileTypeEnum defines the set of file types that can be understood by FTP. 

ascii This is the default file type and is intended for transferring text files. 

Ascii is defined in the Telnet specification to be the lower half of an eitht- 
bit code set (the most significant bit is zero). 

EBCDIC This type is not supported. 

image This type is used for the transfer of binary or compressed data. 

Other This type is used to accommodate other data representations and is 

supported for eight-bit bytes. 
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FileFormatEnum: TYPE * {nonPrint, telnet, asa}; 

The FileFormatEnum defines the set of format control options that can be used with the file 
types Ascii and EBCDIC 

nonPrint This is the default formatting option and indicates there is no formatting 

in the file. 

telnet This indicates the file contains vertical format controls (such as <CR>, 

<LF>, <NL>, <VT>, <FF>). 

asa This indicates the file contains asa (FORTRAN) vertical control 

characters. (See RFC 740 and Communications of the ACM, Vol. 7, No. 
10, p. 606, October 1964). 

FileStructureEnum: TYPE * {file, record, page}; 

The FileStructureEnum defines the set of file structures known to FTP. 

file This is the defaulted file structure. 

record This is not supported. 

page This is not supported. 

LoginlnfoNeeded: TYPE = { 

name, nameAndPassword, nameAndPasswordAndAcct}; 

The type LoginlnfoNeeded describes the types of login information required by the 
authentication mechanism on the FTP server. 

name Only the user's name is required to use the FTP server. 

nameAndPassword The user’s name and password are required to use the FTP 

server. 

nameAndPasswordAndAcct the user must specify name, password and account 

information to use the FTP server. 

ListStyle: TYPE ■ {verbose, terse}; 

The ListStyle type is used with the List procedure to indicate whether verbose (all 
information that can be displayed about the file) or terse (only the file name) is wanted. 

FileStreamProc: TYPE a PROCEDURE [ 

fileName: LONG STRING, options: Options, 
conversationHandle: LONG POINTER] 

RETURNS[ 

statusCode: ArpaFilingCommon.StatusCode, 
fileStream: Stream.Handle, 
put: ArpaFilingCommon.PutProc, 
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get: ArpaFilingCommon.GetProc, 
closeProc: ArpaFilingCommon.CIoseProc]; 

The FileStreamProc type is used by the FTP server when either the store or retrieve 
operations are initiated by the FTP user. The fileName field contains the name of the 
requested file. The options field contains the retrieval options. The conversationHandle 
field contains client information that was passed to the server at user logon time. The 
server client procedure returns whether or not the operation was successful by returning 
the correct statusCode. If the operation was successful, the server client returns a stream 
to the requested file in the field fileStream. The returned stream is used with the get or 
put procedure. The server client need not provide the get procedure when used with the 
store operation but must provide the put procedure. The server client need not provide the 
put procedrue when used with the retrieve operation but must provide the get procedure. 
The closeProc is called when the file transfer is completed. When the closeProc is called, 
no other file operation is performed on the file describe by fileStream. 

LogonProc: TYPE » PROCEDURE [ 
userName, 
userPassword, 

userAccount: LONG STRING <- NIL] 

RETURNS [success: BOOLEAN, conversationHandle: LONG POINTER]; 

The procedure LogonProc is called by the FTP server when the login information is 
received as defined by the parameters of the Register command. The client returns TRUE 
if the information identifies an authenticated user. The field conversationHandle may 
contain client information that is passed with subsequent calls, such as authentication 
information. The server rejects all filing calls made before the user is authenticated. 

QuitProc: TYPE » PROCEDURE [ 

conversationHandle: LONG POINTER]; 

QuitProc is called at the end of a FTP session. The client may free any session information 
at this time. The field conversationHandle contains client information for the current 
session that was passed to the server at user logon time and should be invalidated by this 
call. 

ReinitializeProc: TYPE » PROCEDURE [ 
conversationHandle: LONG POINTER]; 

When the ReinitializeProc is called by the FTP server, the client should consider the 
current session to be open but should set its state back to its initial values. This procedure 
is called when the remote user wishes to destroy the session but maintain the 
communication line as active. The field conversationHandle contains client information 
for the current session that was passed to the server at user logon time and should be 
invalidated by this call. 

RenameProc: TYPE * PROCEDURE [ 
from, to: LONG STRING, 
conversationHandle: LONG POINTER] 

RETURNS [statusCode: ArpaFilingCommon.StatusCode]; 
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RenameProc is called by the FTP server when it receives a request to rename a file. The 
from field contains the current name of the file and the to field contains the new name of 
the file. The field conversationHandle contains client information that was passed to the 
server at user logon time. The client returns a code in statusCode. 

AbortProc: TYPE » PROCEDURE [ 

conversationHandle: LONG POINTER]; 

AbortProc is called by the FTP server when an abort is received from the FTP user. When 
AbortProc is called, the client should suspend and terminate all active processes for the 
specified session. The field conversationHandle contains client information that was 
passed to the server at user logon time. 

DeleteProc: TYPE = PROCEDURE [ 
filePathName: LONG STRING, 
conversationHandle: LONG POINTER] 

RETURNS [statusCode: ArpaFilingCommon.StatusCode]; 

DeleteProc is called by the FTP server when it receives a request to delete a file. The field 
filePathName contains the name of the file to be deleted. The field conversationHandle 
contains client information that was passed to the server at user logon time. The client 
returns the termination status in the field statusCode. 

ListProc: TYPE = PROCEDURE [ 
filePathName: LONG STRING, 
outputProc: OutputListStringProc, 
outputStyle: ListStyle «-terse, 
conversationHandle: LONG POINTER]; 

ListProc is called by the FTP server when it receives a request to list the contents of the 
files specified by the field filePathName. This field may contain wildcard and expansion 
symbols native to the local file system. The type and amount of information returned is 
specified by the field outputStyle. When the value of this field is terse, the client returns 
the name of the files specified by the filePathName field. When the value of the field 
outputStyle is verbose, the client returns a complete list of information about the file or 
files specified by the filePathName field. The procedure specified by outputProc is used to 
return this information to the caller. Individual file information is separated by the Ascii 
character string CR and LF. The field conversationHandle contains client information 
that was passed to the server at user logon time. 

OutputListStringProc: TYPE * PROCEDURE [output: LONG STRING]; 

This procedure type is used with ListProc to send list data to the remote site. 

FTPProcList: TYPE - RECORD [ 
logon: LogonProc, 
quit: QuitProc, 
store: FileStreamProc, 
retrieve: FileStreamProc, 
reinitialize: ReinitializeProc, 
rename: RenameProc, 
abort: AbortProc, 
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delete: DeleteProc, 
list: ListProc, 

print: ArpaFiiingCommon.PrintProc]; 

This type is used with the Register procedure to give the server a list of service commands 
to call when it receives services requests from a remote user. These procedures are 
described above. 

11.11.2 Procedures 
Register: PROCEDURE [ 

ftpProcList: FTPProcList, logonlnfo: LoginlnfoNeeded]; 

This procedure initializes an FTP server process. Only one call to this procedure is valid 
without calling UnRegister. Mutiple calls to this procedure without calling UnRegister 
may produce undefined results. Procedures passed in the field ftpProcList are used to 
satisfy service requests from remote users. The field logonlnfo contains the value for the 
amount of information needed to authenticate remote users, 

UnRegister: PROCEDURE; 

This procedure is used to terminate and unregister the FTP server process initiated by a 
call to the procedure Register. This procedure is currently not implemented. 

11.11.3 References 

RFC740 NETRJS Proctocol - Appendix C f Braden , November , 1977. 

RFC792 Internet Control Message Protocol , Postel , September , 1981. 

RFC793 Transmission Control Protocol, Postel, September, 1981 . 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.12 ArpaSMTP 

The ArpaSMTP interface provides Pilot clients with an interface to the client side of the 
Simple Mail Transfer Protocol (SMTP) defined by RFC821. 

11.12.1 Types and constants 

Handle: TYPE * LONG POINTER TO SMTPObject; 

SMTPObject: TYPE; 

A Handle is a pointer to an SMTPObject representing a connection to a remote SMTP host. 
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Recipients: TYPE ■ LONG POINTER TO RecipientsSequence; 

RecipientsSequence: TYPE ■ RECORD [ 

recipients: SEQUENCE length: CARDINAL OF LONG STRING]: 

The type RecipientsSequence is a sequence of the recipient that a particular message is 
addressed to. 

InvalidRecipientList: TYPE ■ RECORD [ 

invalidRecipients: SEQUENCE length: CARDINAL OF InvalidRecipientRecord]; 

The type InvalidRecipientList is a sequence of all recipients that a post operation could not 
post to. 

InvalidRecipientRecord: TYPE ■ RECORD [ 
recipientName: LONG STRING <- NIL, 
errorReason: SMTPErrorReason, 
errorNumber: CARDINAL]; 

For each invalid recipient of a Post operation an InvalidRecipientRecord is returned. The 
field recipientName is a pointer to the name string that was passed into the Post 
procedure. The errorReason field is the translated error condition as received from the 
remote host. The field errorNumber contains the error number reason of the remote reject. 
This number conforms to the error numbering scheme outlined in RFC821. 

11.12.2 Signals 

SMTPError: SIGNAL [ 

reason: SMTPErrorReason, 
errorNumber: CARDINAL, 
errorstring: LONG STRING]; 

The error SMTPError is raised for all error conditions that arise on the local or remote 
machine. The error reasons are described below. The errorNumber field is reservered for 
error conditions that are reported by the remote SMTP site. Error numbers follow the 
error number definitions as outlined by RFC 821. The errorstring is also reserved for 
remote errors and is the human readable text message that accompanies the SMTP 
errorNumber. The string errorstring is allocated from a private zone and is deallocated on 
unwinding this error. 

SMTPErrorReason: TYPE ■ {addressTranslationError, 

insufficientSpaceOnRemote, invalidName, mailboxUnavailable, remoteError. 
remoteStorageAllocExceeded, serverCommandError, serviceUnavailable, tcpError, 
tcpTimeOut, transactionFailed, userNotLocal}; 

addressTranslationError the remote host name passed is invalid 

insufficientSpaceOnRemote the remote site has insufficient space to process the 

mailing request 

invalidName the specified recipient name is invalid 
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mailboxUnavailable 

remoteError 

remoteStorageAl locExceeded 

serverCommandError 

serviceUnavailable 

tcpError 

tcpTimeOut 

transactionFailed 

userNotLocal 


the specified recipients mailbox is not available 
some remote error 

remote mail storage allocation exceeded 

error in the processing of the SMTP command 

the service must shut down 

some TCP error on connection establishment 

TCP timeout on connection establishment, the 
remote server may no longer be responding 

mail transaction failed 

user is not local to this remote machine; the 
accompanying error string may have an alternate 
path to the user 


11,12.3 Procedures 

Open: PROCEDURE [remoteHost, localHostName: LONG STRING] RETURNS [Handle]; 

Open opens a SMTP connection with the host specified in remoteHost. This procedure can 
raise the SIGNAL SMTPError. The field localHostName contains the name that the local 
host is advertised to the remote server. This name is the common name of the sending 
machine. This procedure returns a connection handle to be used in all subsequent SMTP 
operations. 

Post: PROCEDURE [ 

smtpHandle: Handle, returnPath: LONG STRING, 
recipients: Recipients, message: Stream.Handle] 

RETURNS [success: BOOLEAN, 

badRecipientList: LONG POINTER TO InvalidRecipientList]; 

Post sends a message to the host specified by the smtpHandle field. The field returnPath 
contains the common address of the sender of the message (i.e. 
<userName>@<localHostName>). The recipients field contains a sequence of users 
believed to reside on the host specified by the smtpHandle field to whom the message is 
addressed to. This procedure returns a boolean specifying success or failure in posting the 
message to the specified recipients. If it was not successful, the field badRecipientList 
contains a pointer to a sequence of invalid recipients. Free this field by using the 
procedure FreelnvalidRecipients. 

Verify: PROCEDURE [smtpHandle: Handle, 

user, fullyQualUserName, mailBox: LONG STRING]; 
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The procedure Verify is used to confirm that the string user identifies a known user on the 
host specified by the field smtpHandle. If the the argument user is a user on the remote 
host, the full name of the user (if known) and the fully specified mailbox are returned. 

Expand: PROCEDURE [smtpHandle: Handle, 

distributionList, expandedList: LONG STRING]; 

The procedure Expand asks the host specified by the field smtpHandle to confirm that the 
argument distributionList identifies a mailing list, and if so to return the membership of 
that list. The full name of the users (if known) and the fully specified mailboxes are 
returned. 

Close: PROCEDURE [smtpHandle: Handle]; 

Close ends the existing SMTP connection identified by smtpHandle. The connection 
identified by smtpHandle is invalid after successful completion of this operation and 
should not be used for subsequent operations. 

FreelnvalidRecipients: PROCEDURE [smtpHandle: Handle, 
invalidRecipients: LONG POINTER TO InvalidRecipientList]; 

The procedure FreelnvalidRecipients frees invalid recipients returned by the procedure 
Post. The field smtpHandle is a handle to the SMTP connection and the field 
invalidRecipients is a pointer to the sequence returned by Post. 

11.12.4 References 

RFC821 Simple Mail Transfer Protocol, Postel, August, 1982 . 

An RFC can be copied from the <RFC > directory at SRI’s machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.13 ArpaSMTPServer 

The ArpaSMTPServer interface provides Pilot clients with an interface to the Simple Mail 
Transfer Protocol (SMTP) defined by RFC821. SMTP is a mail transfer protocol to be used 
with the TCP/IP protocols. 

11.13.1 Types and constants 

PostProc: TYPE * PROCEDURE [ 
message: Stream.Handle, 
recipientName, returnPath: LONG STRING]; 

The procedure PostProc is used by the SMTP server when a message is received for the 
user specified by the field recipientName. The message can be received by reading from 
the stream provided in the field message until the signal Stream.EndOfStream is raised. 
The returnPath contains the return mail path to the sender of the message. 
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ExpandProc: TYPE * PROCEDURE [ 
dl: LONG STRING, 

dataProc: PROCEDURE [user, mBox: LONG STRING]]; 

The procedure ExpandProc is used by the SMTP server when a request for distribution list 
expansion is made on the server. The client process returns the distribution list contents 
identified in the field dl by calling the dataProc with each user’s name in the field user and 
mailbox information in the field mBox. 

VerifyProc: TYPE * PROCEDURE [user: LONG STRING] 

RETURNS [fullyQualifiedUser, mailBox: LONG STRING]; 

The procedure VerifyProc is used by the SMTP server when a request for user name 
verification is made on the server. The client process returns the users fully qualified 
name, if known, in the field fullyQualifiedUser and the user’s mailbox identifier in the 
field mailBox. 

ValidateProc: TYPE = PROCEDURE [user: LONG STRING] 

RETURNS [accept: BOOLEAN]; 

The procedure ValidateProc is used by the SMTP server when a request to deposit mail for 
a particular user is made on the server. If the client process is recieving mail for the 
indicated user, it 1 returns TRUE in the field accept. 

PrintProc: TYPE * PROCEDURE [ 
stringToPrint: LONG STRING]; 

The procedure PrintProc is used by the SMTP server to give the client process debugging 
and state information of its actions. The field stringToPrint contains information about 
the current SMTP connections. 

SMTPProcList: TYPE * RECORD [ 
post: PostProc, 
expand: ExpandProc, 
verify: VerifyProc, 
validateUser: ValidateProc, 
print: PrintProc]; 

The SMTPProcList is used to pass the SMTP server a list of procedure that the SMTP server 
uses to communicate with client processes. 

11.13.2 Procedures 

Register: PROCEDURE [ 

smtpProcs: SMTPProcList, serverName: LONG STRING]; 

Register starts an SMTP server session. Only one session is started no matter how many 
calls are made to Register. The fields smtpProcs contains a list of procedure that the 
SMTP server uses to communicate with the client process. The serveName field contains 
the commonly known name of the server. 
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UnRegister: PROCEDURE; 

Unregister stops the SMTP server from recieving any additional connections and releases 
all resources used by the SMTP server. 

11.12.3 References 

RFC821 Simple Mail Transfer Protocol, Postel, August , 1982 . 

An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 

11.14 ArpaMailParse 

The ArpaMailParse parses the headers of messages formatted according to RFC822. 
Syntactic entities from RFC822, such as atom , are indicated by italics in this chapter. 

Essentially, to parse a message call Initialize loop calling GetFieldName, call either 
GetFieldList or NameList (depending on the semantics of the field name returned by 
GetFieldName), and call Finalize. NameList is the main procedure to deal with lists of 
recipients in the many syntactic forms defined by RFC822. Most of the remaining 
procedures in the interface support special cases of these forms and are used infrequently. 

ArpaMailParse is implemented by the program ArpaMailParser Impl. bed. 

11.14.1 Types 

ArpaMailParse.BracketType: TYPE ■ RECORD [ 
group:BOOLEAN false, 
routeAddr: boolean f- false]; 

BracketType, passed to a ProcessProc as part of its Namelnfo argument, describes the 
context of a name in a name list. 

group is TRUE if the name appears in the context " phrase : i.e., phrase is the name of a 

group. This phrase is not treated as part of any recipient name. 

routeAdd is TRUE if the name appears in the context "phrase < i.e., phrase is the 

initial part of a route-addr describing a recipient. 

ArpaMailParse.Handle: TYPE = LONG POINTER TO Object 
ArpaMailParse.Object: TYPE; 

A Handle is a pointer to an Object, representating an instance of a parse. 

ArpaMailParse.NdmelnfO: TYPE ■ RECORD [ 
nesting: ArpaMailParse.BracketType, 
type: ArpaMailParse.NameType]; 
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Namelnfo, used exclusively with the NameList procedure, provides the client-supplied 
process procedure with information about its parameters, nesting describes the context of 
this name in the name list being parsed. If nesting.group or nesting.routeAddr is true, 
then procedure GetGroupPhrase or GetRouteAddrPhrase may be called from the process 
procedure to obtain the phrase for that nesting property. 

ArpaMailParse.NameType: type » {normal, file}; 

NameType, passed to a ProcessProc as part of its Namelnfo argument, describes how the 
local name is interpreted. 

normal The name is a single recipient (neither a file name nor a public 

distribution list). 

file The name occurs as the tag portion of an empty group list and should be 

treated as the name of a file containing a list of recipient names. 

ArpaMailParse.ProcessProc: PROCEDURE [ 
h: A rpa Mai I Parse. Handle, 
local, registry, domain: long string, 
info: Namelnfo]; 

For each recipient encountered, NameList calls the client's ProcessProc, passing it the 
simple name, registry, and Arpanet host. If domain is absent, a string of length zero (not 
nil) is passed. Each is guaranteed to contain room for ArpaMailParse.minLength characters, 
local is always non-empty. The string parameters are free from leading, trailing, and 
excess internal white space, info provides additional information about the name being 
supplied (see the description of Namelnfo for above), domain (but not local) may be 
changed in limited ways by a ProcessProc. It is permissible to either change the length to 0 
or (if the length is 0) append a value to alter the qualification of the name if it is to be 
passed to the write agrument of NameList. h is provided so the client may call 
GetGroupPhrase or GetRouteAddrPhrase. registry is not used. 

ArpaMailParse.WritePrOC; PROCEDURE [string: LONG STRING]; 

Each time the client's ProcessProc returns true, NameList outputs the complete name 
(with possibility altered qualification), by calling the WriteProc with fragments of the 
recipient name. NameList keeps the original format of the name as much as possible, 
including bracketing, comments, and the location of white space. Successive white space 
characters (outside of quoted strings) is replaced by a single space. NameList assumes 
responsibility for outputting appropriate separators (commas) and brackets, based on the 
values returned by successive invocations of process. 

11.14.2 Constants and data objects 

ArpaMailParse.endOflnput: CARDINAL - ...; 

endOflnput should be returned by the client's next procedure (see Initialize) when the end 
of the input is reached. 

ArpaMailParse.endOfList: CARDINAL s 
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endOf List may be used as a delimiter terminating a list of names. It has no other effect. 

ArpaMailParse.minLength: CARDINAL = 40; 

The registry and domain strings passed to the client’s ProcessProc will be at least this 
long. 

11.14.3 Signals and errors 

ArpaMaiiParse.Error: error [code: ArpaMailParse.ErrorCode, position: cardinal]; 

Error is raised when the parse of the mail message fails, code describes the reason for the 
failure, position is the number of characters parsed when the error was detected. 

ArpaMailParse.ErrorCode: TYPE ■ { 

illegalCharacter, unclosedBracket, bracketNesting, implementationBug, 
phraseExpected, domainExpected, atomExpected, commaOrColon Expected, 
at Expected, spacelnLocalName, mailBox Expected, missingSemiCoion, nestedGroup, 
endOflnput, commaExpected,fieldsAreAtoms, colonExpected, lessThanExpected, 
greaterThanExpected, noFromField}; 

The error conditions that cause a failure are largely self-explanatory. noFromField is not 
raised by ArpaMaiiParse, but is provided for clients who cannot succeed if the message is 
either unparseable or contains no "From:” field. 

11.14.4 Procedures 

ArpaMaiiParse. Finalize: PROCEDURE [h: ArpaMaiiParse. Handle]; 

FinalizeParse finalizes the parse. This procedure must be called when the client has 
finished parsing, after either normal completion or an error has occurred. Finalize modifies 
h, so it should not be reused. Note: Finalize may not be called from within the process 
procedure invoked by NameList or from within the catch phrase of Error. 

ArpaMailParse.GetFieldBody: PROCEDURE [ 

h: ArpaMaiiParse. Handle, string: long string, suppressWhiteSpace: boolean <-false]; 

GetFieldBody reads the remainder of the current field body using next (see Initialize) and 
puts the characters consumed into string. If the field body is too long, overflow characters 
are discarded. If the field body terminates before a CR is seen, Error[endOfInput] is raised. 
Upon return, string has no initial or terminal white space (blanks and tabs) and, if 
suppressWhiteSpace is true, each internal run of white space is replaced by a single 
blank. RFC822 line-folding conventions are also observed. 

ArpaMaiiParse. GetFieldName: PROCEDURE [h: ArpaMai!Parse.Handle,field:LONG STRING] 
returns [found: boolean]; 

GetFieldName presumes that next (see Initialize) is positioned to read the first character of 
a field name and it returns the field name, without the terminating colon, in field. It 
leaves next ready to return the first character following the colon (or, if the end of the 
message header has been reached, the character (if any) after the two CRs that normally 
terminate the header). If the field name is too long, overflow characters are discarded. 
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Upon return, found is false if no field names remain in the header. If the header field ends 
prematurely or illegal header characters are encountered, ErrorffieldsAreAtoms] is 
raised. Error[colonExpected] is raised if there are embedded spaces in the field name. 

ArpaMaiiParse.GetGroupPhrase: procedure [h: ArpaMaiiParse. Handle, phrase: long string]; 

GetGroupPhrase can only reasonably be called from inside the process procedure passed 
to NameList. The phrase that introduces the current group is appended to phrase. If the 
phrase is too long, overflow characters are discarded. Upon return, phrase has no initial or 
terminal white space (blanks and tabs, and each internal run of white space is replaced by 
a single blank. If GetGroupPhrase is called at an inappropriate time (for example, when 
Namelnfo.nesting.group ■ false), no changes are made to phrase. 

ArpaMailParse.GetRouteAddrPhrase: procedure [h: ArpaMailParse.Handle, name: LONG STRING]; 

GetRouteAddrPhrase can only reasonably be called from inside the process procedure 
passed to NameList. The phrase that describes the current recipient is appended to name. 
If the phrase is too long, overflow characters are discarded. Upon return, name has no 
initial or terminal white space (blanks and tabs), and each internal run of white space has 
been replaced by a single blank. If GetRouteAddrPhrase is called at an inappropriate time 
(e.g., when Namelnfo.nesting.routeAddr » false), no changes will be made to name. 

ArpaMailParse.lnitialize: procedure [next: procedure returns [character], 

RETURNS [ArpaMailParse.Handle]; 

Initialize creates an instance of the header parser and returns a Handle to be passed to 
other procedures of this interface. Subsequent invocations of GetFieldName, 
GetFieldBody, and NameList obtain their input using next. 

ArpaMailParse. NameList: PROCEDURE [ 

hArpaMailParse.Handle, process: ArpaMailParse.ProcessProc, write: ArpaMailParse.WriteProc 
<-nil]; 

The NameList procedure expects to read characters using next (see Initialize) for a 
structured field body consisting of a list of recipient names. For each name encountered, it 
calls process. If process returns true and write is not nil, NameList outputs the complete 
name, with potentially altered qualification, by calling write. If any syntax errors are 
detected during parsing, Error is raised. It is legitimate for the process procedure to raise a 
signal that causes NameList to be unwound. 

ArpaMailParse.StringForErrorCode: procedure [code: ArpaMailParse.ErrorCode, s: long string]; 

StringForErrorCode appends a user-sensible error message onto the string s. If the error 
message is too long, overflow characters are discarded. 

11.14.5 References 

RFC822 Standard for the Format of ARP A - Internet Text Messages , Crocker , August , 1982 
An RFC can be copied from the < RFC > directory at SRFs machine: 

SRI - NIC.ARPA 

using FTP with username, ANONYMOUS, and password, GUEST. 


11-42 




A 


Performance Criteria 


This appendix contains quantitative information about the observed performance of Pilot 
and information about how client programs are expected to behave. Where machine 
dependencies are a factor, it is assumed that the machine is a Dandelion. Some effort has 
been expended in describing the source of and confidence in the figures presented. These 
figures are presented to convey the flavor of the system rather than as hard performance 
guarantees. In general, crisp and quantitative performance requirements for Pilot are not 
available for comparison with the figures presented here. 

A.l Physical memory requirements of Pilot 

The resident part of Pilot, the part that is ineligible for swapping, is 113 pages (28,928 
words). It is allocated as follows: code - 51, data - 36, the Mesa runtime data structures - 19, 
and global frames - 7. As far as memory usage is concerned, this is the only machine 
dependent part of Pilot. 


Most Pilot functions will require additional code and data to be swapped in. The memory 
requirements for Pilot functions are given in terms of working sets. A working set for a 
function is defined to be those virtual pages (code and data) which, if they are all in 
memory, provide a local minimum of page faults to service the function. 


Because there is a significant overlap of code and data between one Pilot function and 
another, it is not possible to simply add up the sizes of all the working sets one anticipates 
using to get the total amount of memory required for a task. 


Working set sizes are given in pages. They do not include the resident. 


Pilot Function 

Working 
Set Size 

Notes 

Communication 

Idle 

15 


First Connection 

13 

Does not include Idle 

Subsequent Connections 2- 17 

Does not include first'connection 
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Working 

Pilot Function Set Size 

File 

Create 26 

Delete 25 

SetSize 28 

Floppy Channel 8 

Heap 

MakeNode 4 

FreeNode 4 

Signals 7 

Space 

Allocate 9 

Deallocate 14 

Map At 21 

UnmapAt 6 

Streams 1 


A.2 Execution speed and client program profile 

This section enumerates some typical characteristics which Pilot expects or will support in 
its clients. These estimates are intended to assist the client programmer in designing his 
use of Pilot facilities. They provide guidelines about which facilities are expensive and 
thus to be used sparingly and which facilities are inexpensive and can be exercised 
heavily. None of these estimates are binding on either Pilot or client programs . Pilot 11.0 
may deviate from these figures 


These estimates apply to the cumulative load imposed by all clients operating on a single 
system element. A particular client program or system which does not exercise any of the 
resources very heavily may share the system element with other client programs, 
provided that the sum of their requirements remains within the estimates set out below. 


A.2,1 Memory management 

The following figures indicate the dynamic cost of virtual memory in terms of disk 
accesses, CPU time, and real time for a particular disk unit. 

Facility Minimum Typical Maximum 

disk accesses to create 


or delete a space 

0 

2 

>4 

number of disk accesses to 




handle a page fault 

0 

1 

>2 

cpu time to handle a page fault 

4-5 msec 

6-8 msec 

- 

real time to handle a page fault 1 >2 

5-7 msec 

45-55 msec 

>0.1 sec 


^Paging from the local Shugart 4008 disk. Real time per disk access = 1 - 200 milliseconds. 
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-No quanmtve as t.n rh<» maximum firm* to service a pa^c fault will <»Y(»r bo I'ivmn. In th»* raso that thf* 
bisk is occupied with real unu* prnrrssim*, pa«*e fault handling times of several seconds or more ran 
occur. The maximum time stated is the max time exclusive of such situations. 


A.2.2 File management 


The following figures indicate the typical characteristics of the Pilot file system. In this 
table, the term "active file" means a file which has been referenced recently so that its 
location and description are still present in the Pilot's caches. 


Facility 
total drives 

(i.e., active physical volumes) 

total existing files per volume 

rate of file creation and 
deletion (long term average) 

size of files (in pages) 

number of volume pages 
allocated as a unit 

number of file pages 
accessed in a sequence* 


Typical 


l 


4 

8 


l Limited by the amount of real memory for the access sequence. 


Maximum 


16 

1/disk page 


8 * 106 

8 * 106 


8 * 106 


A.2.3 Communication via the Ethernet 

The following figures indicate the expected performance of communication between 
system elements connected to the same Ethernet. 

Facility Maximum 

memory-to-memory transfer 

through the Stream interface 7.5 * 10 5 bits/sec 

A.2.4 Processes 

The following table provides data about the expected processing time on the Dandelion of 
each of the process structuring facilities. 


Facility 

Minimum 

Typical 

Maximum 

Monitor entry or exit 

3 //sec. 

<4//sec. 

5 //sec. 

Process switch time 

25 //sec. 

30 //sec. 

40 //sec. 

Fork or Join^ 

0.7 msec. 

1 msec. 

1.5 msec. 
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Facility 

Minimu m 

Typical 

Maximum 

WaitU 

10 //sec. 

< 60 //sec. 

100 //sec. 

Notify* 

10 //sec. 

15//sec. 

20//sec. 


l Exclusive of process switchi ng time. 

^The wide range on this facility reflects a current lack of data about its operating time rather than a 
dynamic variation in the final product. 
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In Pilot, every file must be assigned a type code at the time it is created. This code is of 
type File.Type and is constant for the life of the file. It provides a means for Pilot, various 
scavenging programs, and clients to recognize the purpose for which each file was 
intended. This is especially important because files on Pilot disks do not inherently have 
meaningful strings for names, making it difficult for a human user or programmer to 
recognize which file is which To make this principle work effectively, each different kind 
of file should be assigned its own unique type. This appendix describes how the type codes 
are assigned. 

The center of this scheme is the FileTypes interface, maintained by the Pilot group. In this 
file are defined all subranges of File.Type assigned to individual client and application 
groups. This module is designed so that it can be recompiled whenever a new type is 
assigned without invalidating any old version. Thus, within certain limits, a program 
may include any version of FileTypes which contains the type codes of interest to it without 
building in an unnecessary or awkward compilation dependency. 

The basic structure of FileTypes is a set of subrange and constant definitions of the following 
form: 

PilotFileType: type = cardinal [0..256); 

MesaFileType: type a cardinal [256..512); 

DCSFileType: type = cardinal [512..768); 

... — Subranges assigned to other clients and subsystems 

The subranges are designed to allow individual client organizations to administer their 
own file type assignment for their own purposes. Each group should maintain a module of 
the same form as FileTypes and include FileTypes in its directory clause. Such a module would 
be used to assign types within the subrange allocated to that group while still providing a 
measure of protection against conflicting assignment by independent groups. The 
structure of this module should be similar to that of FileTypes in order that the assignment 
of a new type code does not trigger a universal recompilation of the subsystem. 


B-l 




B 


Managing and Assigning File Types 


For example, the Mesa Development Environment group is assigned the subrange of file 
types [9280..9344) to allocate as the> see fit. This allocation is managed by the module 
MesaDEFileTypes, of the following form: 

DIRECTORY 

File: using [Type], 

FileTypes: using [MesaOEFileType]; 

MesaOEFileTypes: definitions 3 

BEGIN 

MesaDEFileType: type = FileTypes. MesaOEFileType; 

— MesaDE File Types 

tUnassigned: File.Type * [MesaDEFileTypefFiRSTfMesaDEFileType]]]; 
tRootDirectory: Fiie.Type ■ [tUnassigned *► 1]; 
tDi rectory: File.Type » [ tRootDi rectory ♦ 1]; 

• . . -- Other file types for use by Mesa 
END. 

This module can be recompiled independently of the module FileTypes, for example each 
time a new type code is added by the Mesa Development Environment group. All of mesa 
environment would derive the type codes for its files from this module 

In a similar manner, types within the subrange PilotFileType, for file types used by Pilot 
itself, are found in a private Pilot definitions module. 

It is possible for two different program modules or configurations which include two 
different versions of F i leTypes . bed (or any of its derivatives, such as 
MesaOEFileTypes.bed) to be bound together without error or conflict. This situation 
can arise, for example, because one configuration was compiled prior to the assignment of 
a new file type while the other was compiled afterwards. A problem occurs, however, if a 
module includes (either directly or indirectly) two different files defining file types. In this 
case, the compiler will refuse to compile the module unless the same version is used in 
both cases. For example, if a program includes both FileTypes and MesaOEFileTypes, and if 
FileTypes .mesa was updated after MesaOEFileTypes . bed was created, then the Mesa 
compiler would generate an error message about FileTypes being used in differing versions. 
This error would also be generated if the program included FileTypes indirectly, say, by 
including another definitions module which itself had included a different version of 
FileTypes. 

This problem should not, however, occur in a well-structured system design. For example, 
a file of type tWidget is perceived as such only by the module or modules which actually 
implement widget objects. All other modules use only a well-defined interface and deal in 
widgets, not widget implementations; i.e., the underlying file and its type are hidden. 
Since a single module will not be involved in the implementation of abstractions from two 
widely separated parts of the NS world, it need not see two different modules both defining 
separate ranges of type codes for files. 

Therefore, the following style rules are recommended: 

a. FileTypes. bed and its derivatives should be included only in program modules, not 
in definitions modules. 
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b. Only one module defining the type codes for files should be included in any program 
(e.g., do not include both FileTypes and Mesa DE File Types). 

c. The Pilot group will keep PileTypes. mesa and FileTypes•bed up-to-date in 
conspicuous places, on the release directory between releases of Pilot. 

d. All programs, including Pilot, Common Software, and applications, should use type 
codes only symbolically from modules in which they are assigned. No program should 
fabricate a value of type File.Type from a numeric constant. 

If all clients of Pilot observe these rules and the style of using Mesa definitions modules of 
the form of FileTypes, the job of administering the assignment of type codes for Pilot files can 
be kept manageable In return, the Pilot group can react immediately to requests for a 
new type code or subrange of type codes. If this style is not observed, the administration of 
global constants such as these will become a complicated, time-consuming task with a 
corresponding difficulty in reacting quickly to requests. 
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Pilot’s Interrupt Key Watcher 


This appendix describes the operation of the interrupt key watcher that can be enabled by 
users or clients at boot time, via boot switch 8 

If one goes to the debugger and then does an interpret call, the interpret call is executed in 
the process that went to the debugger, and consequently runs at that process’s priority. If 
this is a priority at which the taking of faults is restricted, the interpret call may fault and 
block trying to allocate state vectors. 

If Pilot is booted with the 8 boot switch, pressing LOCK-LeftSHiFT-RightSHiFT-STOP will cause 
Pilot to call the debugger with the message "Pilot Emergency Interrupt". This is done at a 
priority level that precludes doing any interpret calls from the debugger 
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Systems that are based on PilotKernel.bcd require that a disk be present on the machine. 
The boot file containing the system must be installed on the disk, from which it is loaded 
into the processor memory when the system is booted. The disk contains the system 
physical and logical volumes for the system (i.e., those on which the boot file is located). 

Systems that are based on UtilityPilotKernel.bcd do not require that a disk be present on 
the machine. The boot file containing the system may be loaded from any source, e.g., 
ethernet, floppy disk. UtilityPilot provides the same facilities as regular Pilot, with the 
following exceptions: 

• There are no system physical and logical volumes. 

• No volumes are brought online as part of Pilot initialization. 

• The entire system and its working data must fit into the real memory of the 
processor. (Backing storage provided by Space.ScratchMap and the system heaps 
come from real memory) 

• Clients must validate/set local time parameters before calling any pilot facility that 
needs them. 

• Map logging is disabled. 

• Run-time loading is not supported. 

UtilityPilot is commonly used to build special utility systems, such as, disk initializers 
and diagnostics. 
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Multi-national Considerations 


The hardware and software described in this manual support serial communication via 
the RS-232-C controller in accordance with EIA standard RS-232-C. No support is 
provided for CCITT Recommendations V.24 and V.27, the equivalent prevailing standard 
in most of Europe. 
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. References 

F.l Mandatory references 

The following documents should be studied before or in conjunction with this document: 

• Courier: The Remote Procedure Call Protocol , XSIS 038112 

• Mesa Language Manual--610EQ0110 

• XDE User's Guide --610E00140 

• Mesa Programmer's Manual-- 610E00150 

In addition, the release documentation accompanying each release of Pilot should be 
consulted before writing programs that use Pilot. 

F.2 Informational references 

The following documents provide useful additional information: 

• The Ethernet , A Local Area Network , Data Link Layer , and Physical Layer 
Specifications , Version LO . [September 30,1980] 

• Xerox Internet Transport Protocols. [February 1982] 
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SetRootNode, 4-46 
SetSize, 4-21,8-14 
SetSST, 3-7, 3-7, 3-12 
SetSSTProcedure, 3-16 
SetState, 4-56, 5-14 
SetSwitches, 8-11, 8-12 
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Space 

DEFINITIONS, 4-29 
space machinery 
storage, 4-43 
SpaeeUsage 

DEFINITIONS, 4-29 
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